Esc

↑↓ move↵ openIndex · Pagefind
REST reference · Accounting · Money in and out

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.

98 operationsCompany moduleAll Accounting apps →
  1. GET /rest/v1.0/companies/{company_id}/accounting/ap/agingAP aging as of a date
  2. GET /rest/v1.0/companies/{company_id}/accounting/ap/automation/settingsGet AP automation settings
  3. PATCH /rest/v1.0/companies/{company_id}/accounting/ap/automation/settingsUpdate AP automation settings
  4. GET /rest/v1.0/companies/{company_id}/accounting/ap/backup_noticesList CP2100 B notices
  5. POST /rest/v1.0/companies/{company_id}/accounting/ap/backup_noticesRecord a CP2100 B notice
  6. PATCH /rest/v1.0/companies/{company_id}/accounting/ap/backup_notices/{id}Mark a B notice letter sent or record the cure
  7. GET /rest/v1.0/companies/{company_id}/accounting/ap/backup_notices/{id}/letterB notice letter
  8. GET /rest/v1.0/companies/{company_id}/accounting/ap/billsList bills and vendor credits
  9. POST /rest/v1.0/companies/{company_id}/accounting/ap/billsCreate a draft bill or vendor credit
  10. GET /rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}Show a bill
  11. PATCH /rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}Edit a draft or pending bill
  12. DELETE /rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}Delete a draft bill
  13. POST /rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/apply_creditApply a vendor credit to a bill
  14. POST /rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/approveApprove a bill
  15. GET /rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/attachmentsList attachments on a bill
  16. POST /rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/attachmentsAttach a file to a bill
  17. POST /rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/override_holdOverride a hold
  18. POST /rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/rejectReject a bill (return to the preparer)
  19. POST /rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/release_retainageRelease retainage payable
  20. POST /rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/rematchRe-run the three-way match
  21. POST /rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/submitSubmit a bill for approval
  22. POST /rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/unapply_creditUndo a vendor credit application
  23. POST /rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/voidVoid a posted bill
  24. POST /rest/v1.0/companies/{company_id}/accounting/ap/bills/from_sourceDraft a bill from a requisition or direct cost
  25. GET /rest/v1.0/companies/{company_id}/accounting/ap/capture/documentsList the capture inbox
  26. POST /rest/v1.0/companies/{company_id}/accounting/ap/capture/documentsUpload a bill document to the capture inbox
  27. GET /rest/v1.0/companies/{company_id}/accounting/ap/capture/documents/{id}Get a captured document
  28. PATCH /rest/v1.0/companies/{company_id}/accounting/ap/capture/documents/{id}Key, assign or progress a captured document
  29. POST /rest/v1.0/companies/{company_id}/accounting/ap/capture/documents/{id}/draft_billDraft a bill from a captured document
  30. GET /rest/v1.0/companies/{company_id}/accounting/ap/capture/documents/{id}/fileDownload a captured file
  31. POST /rest/v1.0/companies/{company_id}/accounting/ap/capture/documents/{id}/rejectReject a captured document
  32. GET /rest/v1.0/companies/{company_id}/accounting/ap/capture/documents/{id}/suggestionsCoding suggestions for a captured document
  33. POST /rest/v1.0/companies/{company_id}/accounting/ap/checks/{id}/reprintReprint a check under a new number
  34. GET /rest/v1.0/companies/{company_id}/accounting/ap/compliance_requirementsList compliance requirements
  35. POST /rest/v1.0/companies/{company_id}/accounting/ap/compliance_requirementsRequire a compliance document
  36. DELETE /rest/v1.0/companies/{company_id}/accounting/ap/compliance_requirements/{id}Drop a compliance requirement
  37. GET /rest/v1.0/companies/{company_id}/accounting/ap/form_10991099 review
  38. GET /rest/v1.0/companies/{company_id}/accounting/ap/form_1099/copy_b1099 recipient Copy B
  39. POST /rest/v1.0/companies/{company_id}/accounting/ap/form_1099/irisExport 1099s as IRIS Taxpayer Portal CSV files
  40. POST /rest/v1.0/companies/{company_id}/accounting/ap/form_1099/pub1220Export 1099s as an IRS Pub 1220 file
  41. GET /rest/v1.0/companies/{company_id}/accounting/ap/form_945Form 945 data
  42. POST /rest/v1.0/companies/{company_id}/accounting/ap/form_945/eftpsEFTPS 945 deposits
  43. GET /rest/v1.0/companies/{company_id}/accounting/ap/match_exceptionsList three-way match exceptions
  44. GET /rest/v1.0/companies/{company_id}/accounting/ap/match_exceptions/{id}Show a match exception
  45. POST /rest/v1.0/companies/{company_id}/accounting/ap/match_exceptions/{id}/overrideOverride a match exception
  46. GET /rest/v1.0/companies/{company_id}/accounting/ap/payment_runsList payment runs
  47. POST /rest/v1.0/companies/{company_id}/accounting/ap/payment_runsCreate a draft payment run
  48. GET /rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}Show a payment run
  49. DELETE /rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}Delete a draft run
  50. GET /rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}/checksCheck print data
  51. GET /rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}/nachaACH (NACHA) file
  52. POST /rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}/nachaRe-send the ACH (NACHA) file
  53. GET /rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}/positive_payPositive pay file (CSV)
  54. POST /rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}/rejectReject a payment run release
  55. POST /rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}/releaseRelease (approve) and post a payment run
  56. GET /rest/v1.0/companies/{company_id}/accounting/ap/payment_selectionPayment selection
  57. GET /rest/v1.0/companies/{company_id}/accounting/ap/paymentsList payments
  58. POST /rest/v1.0/companies/{company_id}/accounting/ap/paymentsCreate one manual payment
  59. GET /rest/v1.0/companies/{company_id}/accounting/ap/payments/{id}Show a payment
  60. GET /rest/v1.0/companies/{company_id}/accounting/ap/payments/{id}/remittanceGet a payment's remittance advice
  61. POST /rest/v1.0/companies/{company_id}/accounting/ap/payments/{id}/remittance/sendEmail a payment's remittance advice
  62. POST /rest/v1.0/companies/{company_id}/accounting/ap/payments/{id}/virtual_card/issueRetry a virtual card issue
  63. POST /rest/v1.0/companies/{company_id}/accounting/ap/payments/{id}/voidVoid a payment
  64. GET /rest/v1.0/companies/{company_id}/accounting/ap/receiptsList PO receipts
  65. POST /rest/v1.0/companies/{company_id}/accounting/ap/receiptsReceive against a purchase order
  66. POST /rest/v1.0/companies/{company_id}/accounting/ap/receipts/{id}/voidVoid a PO receipt
  67. POST /rest/v1.0/companies/{company_id}/accounting/ap/retainage_releases/{id}/voidVoid a retainage release
  68. GET /rest/v1.0/companies/{company_id}/accounting/ap/settingsAP settings
  69. PATCH /rest/v1.0/companies/{company_id}/accounting/ap/settingsUpdate AP settings
  70. GET /rest/v1.0/companies/{company_id}/accounting/ap/tie_outAP subledger tie-out
  71. POST /rest/v1.0/companies/{company_id}/accounting/ap/tin_matching/exportExport an IRS bulk TIN Matching request file
  72. POST /rest/v1.0/companies/{company_id}/accounting/ap/tin_matching/importImport IRS bulk TIN Matching results
  73. GET /rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/bank_change_requestsList portal bank change requests
  74. POST /rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/bank_change_requests/{id}/forwardForward a bank change request for approval
  75. POST /rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/bank_change_requests/{id}/rejectReject a bank change request
  76. GET /rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/grantsList vendor portal users
  77. POST /rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/grants/{id}/revokeRevoke a vendor portal user's access
  78. GET /rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/invitationsList vendor portal invitations
  79. POST /rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/invitationsInvite a user to a vendor's portal
  80. POST /rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/invitations/{id}/revokeRevoke a pending invitation
  81. GET /rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/submissionsList portal compliance submissions
  82. POST /rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/submissions/{id}/acceptAccept a portal compliance submission
  83. POST /rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/submissions/{id}/rejectReject a portal compliance submission
  84. GET /rest/v1.0/companies/{company_id}/accounting/ap/vendorsList AP vendors
  85. GET /rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}Show an AP vendor
  86. GET /rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/attachmentsList attachments on a vendor
  87. POST /rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/attachmentsAttach a file to a vendor
  88. GET /rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/automationGet a vendor's remittance and capture settings
  89. PATCH /rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/automationUpdate a vendor's remittance and capture settings
  90. POST /rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/complianceRecord a compliance document
  91. PATCH /rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/compliance/{compliance_id}Lift or reinstate a compliance record
  92. 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)
  93. 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)
  94. POST /rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/lien_waiversRecord a lien waiver received
  95. GET /rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/lien_waivers/{waiver_id}/attachmentsList attachments on a lien waiver
  96. POST /rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/lien_waivers/{waiver_id}/attachmentsAttach a file to a lien waiver
  97. GET /rest/v1.0/companies/{company_id}/accounting/ap/virtual_cardsList virtual card payments
  98. 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/aging

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • as_of
    string (date)query
  • basis
    stringquery
    One of: due, document.

Response · 200 · object

  • as_of
    string (date)required
  • basis
    stringrequired
  • bucket_labels
    string[]required
  • rows
    object[]required
  • rows[].vendor_id
    integerrequired
  • rows[].vendor_name
    string | nullrequired
  • rows[].buckets
    string[]required
  • rows[].retainage
    stringrequired
    Money, 2 dp
  • rows[].total
    stringrequired
    Money, 2 dp
  • totals
    objectrequired
  • totals.buckets
    string[]required
  • totals.retainage
    stringrequired
    Money, 2 dp
  • totals.total
    stringrequired
    Money, 2 dp

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 422Validation failed or the ledger refused the change

Example request

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

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • capture_enabled
    booleanrequired
  • capture_address
    string | null
    ap+<token>@ACCT_AP_CAPTURE_DOMAIN; null when capture by email is not deployed.
  • capture_allowed_senders
    string[]
  • portal_enabled
    booleanrequired
  • remittance_enabled
    booleanrequired
  • virtual_card_enabled
    booleanrequired
  • virtual_card_provider
    string
  • virtual_card_clearing_account_id
    integer | null
  • virtual_card_funding_bank_account_id
    integer | null
  • updated_at
    string | null (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/automation/settings" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Payable

PATCH /rest/v1.0/companies/{company_id}/accounting/ap/automation/settings

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

v1.0Implemented

Parameters

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

Request body

  • automation_settings
    objectrequired
  • automation_settings.capture_enabled
    boolean
  • automation_settings.capture_allowed_senders
    string[]
  • automation_settings.rotate_capture_address
    boolean
  • automation_settings.portal_enabled
    boolean
  • automation_settings.remittance_enabled
    boolean
  • automation_settings.virtual_card_enabled
    boolean
  • automation_settings.virtual_card_clearing_account_id
    integer | null
  • automation_settings.virtual_card_funding_bank_account_id
    integer | null

Response · 200 · object

  • capture_enabled
    booleanrequired
  • capture_address
    string | null
    ap+<token>@ACCT_AP_CAPTURE_DOMAIN; null when capture by email is not deployed.
  • capture_allowed_senders
    string[]
  • portal_enabled
    booleanrequired
  • remittance_enabled
    booleanrequired
  • virtual_card_enabled
    booleanrequired
  • virtual_card_provider
    string
  • virtual_card_clearing_account_id
    integer | null
  • virtual_card_funding_bank_account_id
    integer | null
  • updated_at
    string | null (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed

Example request

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

List CP2100 B notices

B notice records, newest first. Filter with vendor_id. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • notice_number
    integerrequired
    One of: 1, 2.
  • notice_date
    string (date)required
  • tax_year
    integer | nullrequired
  • letter_due_by
    string (date)required
    notice_date + 15 IRS business days (Pub 1281).
  • withhold_from
    string (date)required
    notice_date + 30 IRS business days: 24% backup withholding applies to AP payments from this date until cured.
  • letter_sent_at
    string | null (date)required
  • cured_at
    string | null (date)required
  • cure_kind
    string | nullrequired
    One of: w9, ssa_card, letter_147c, letter_685c, letter_096c, null.
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/backup_notices" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Payable

POST /rest/v1.0/companies/{company_id}/accounting/ap/backup_notices

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

v1.0Implemented

Parameters

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

Request body

  • backup_notice
    objectrequired
  • backup_notice.vendor_id
    integerrequired
  • backup_notice.notice_date
    string (date)required
  • backup_notice.tax_year
    integer | null
  • backup_notice.notice_number
    integer | null
    One of: 1, 2, null.

Response · 201 · object

  • id
    integerrequired
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • notice_number
    integerrequired
    One of: 1, 2.
  • notice_date
    string (date)required
  • tax_year
    integer | nullrequired
  • letter_due_by
    string (date)required
    notice_date + 15 IRS business days (Pub 1281).
  • withhold_from
    string (date)required
    notice_date + 30 IRS business days: 24% backup withholding applies to AP payments from this date until cured.
  • letter_sent_at
    string | null (date)required
  • cured_at
    string | null (date)required
  • cure_kind
    string | nullrequired
    One of: w9, ssa_card, letter_147c, letter_685c, letter_096c, null.
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 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

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

v1.0Implemented

Parameters

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

Request body

  • backup_notice
    objectrequired
  • backup_notice.letter_sent_at
    string | null (date)
  • backup_notice.cured_at
    string | null (date)
  • backup_notice.cure_kind
    string | null
    One of: w9, ssa_card, letter_147c, letter_685c, letter_096c, null.

Response · 200 · object

  • id
    integerrequired
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • notice_number
    integerrequired
    One of: 1, 2.
  • notice_date
    string (date)required
  • tax_year
    integer | nullrequired
  • letter_due_by
    string (date)required
    notice_date + 15 IRS business days (Pub 1281).
  • withhold_from
    string (date)required
    notice_date + 30 IRS business days: 24% backup withholding applies to AP payments from this date until cured.
  • letter_sent_at
    string | null (date)required
  • cured_at
    string | null (date)required
  • cure_kind
    string | nullrequired
    One of: w9, ssa_card, letter_147c, letter_685c, letter_096c, null.
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (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

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

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • filename
    stringrequired
  • text
    stringrequired
  • envelope
    stringrequired
  • letter_due_by
    string (date)required
  • notice_number
    integerrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • page
    integerquery
  • per_page
    integerquery
  • filters[status]
    stringquery
  • filters[kind]
    stringquery
  • vendor_id
    integerquery
  • project_id
    integerquery
  • due_by
    string (date)query
  • search
    stringquery
  • updated_since
    string (date-time)query
    Delta 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.
  • cursor
    stringquery
    Opaque keyset cursor from a previous response's Next-Cursor header; each page costs the same however deep it is.

Response · 200 · object[]

  • id
    integerrequired
  • number
    stringrequired
  • kind
    stringrequired
    One of: bill, credit.
  • status
    stringrequired
    One of: draft, pending_approval, posted, void.
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • entity_id
    integerrequired
  • invoice_number
    string | nullrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • term_id
    integer | nullrequired
  • discount_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • discount_date
    string | null (date)required
  • memo
    string | nullrequired
  • total
    stringrequired
    Money, 2 dp
  • retainage_amount
    stringrequired
    Money, 2 dp
  • use_tax_amount
    stringrequired
    Money, 2 dp
  • tax_code_id
    integer | nullrequired
  • open_amount
    stringrequired
    Money, 2 dp
  • retainage_open
    stringrequired
    Money, 2 dp
  • paid_amount
    stringrequired
    Money, 2 dp
  • retainage_released
    stringrequired
    Money, 2 dp
  • commitment_type
    string | nullrequired
  • commitment_id
    integer | nullrequired
  • requisition_id
    integer | nullrequired
  • direct_cost_id
    integer | nullrequired
  • pay_when_paid_pay_app_id
    integer | nullrequired
  • pay_when_paid_mode
    string | nullrequired
  • off_rent_date
    string | null (date)required
  • billed_through
    string | null (date)required
  • match
    object | nullrequired
  • hold_overrides
    object[]required
  • revision
    integerrequired
  • prepared_by_id
    integerrequired
  • last_edited_by_id
    integerrequired
  • contributor_ids
    integer[]required
    Every user who created or edited the bill. None of them may approve it, override its holds or release its payment.
  • submitted_at
    string | null (date-time)required
  • approved_at
    string | null (date-time)required
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • lines
    object[]
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].description
    string | nullrequired
  • lines[].amount
    stringrequired
    Money, 2 dp
  • lines[].retainage_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].retainage_amount
    stringrequired
    Money, 2 dp
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].equipment_id
    integer | nullrequired
  • lines[].commitment_line_item_id
    integer | nullrequired
  • lines[].quantity
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].unit_price
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].use_tax
    booleanrequired
  • lines[].reportable_1099
    booleanrequired
  • lines[].tax_category
    string | nullrequired
    Contractor 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_ids
    array | nullrequired
    User-defined dimension values (AcctDimensionValue ids).

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/bills" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Payable

POST /rest/v1.0/companies/{company_id}/accounting/ap/bills

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

v1.0Implemented

Parameters

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

Request body

  • bill
    objectrequired
  • bill.kind
    string
  • bill.vendor_id
    integerrequired
  • bill.entity_id
    integer | null
  • bill.invoice_number
    string | null
  • bill.invoice_date
    string (date)required
  • bill.posting_date
    string (date)
  • bill.due_date
    string (date)
  • bill.term_id
    integer | null
  • bill.memo
    string | null
  • bill.retainage_percent
    string | null
  • bill.tax_code_id
    integer | null
  • bill.commitment_type
    string | null
  • bill.commitment_id
    integer | null
  • bill.pay_when_paid_pay_app_id
    integer | null
  • bill.pay_when_paid_mode
    string | null
  • bill.off_rent_date
    string | null (date)
  • bill.billed_through
    string | null (date)
  • bill.duplicate_override_reason
    string | null
  • bill.inactive_vendor_override_reason
    string | null
    Bill 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.lines
    object[]required
  • bill.lines[].account_id
    integerrequired
  • bill.lines[].amount
    stringrequired
  • bill.lines[].description
    string | null
  • bill.lines[].retainage_percent
    string | null
  • bill.lines[].retainage_amount
    string | null
    Explicit retainage (at most the line amount); overrides retainage_percent.
  • bill.lines[].project_id
    integer | null
  • bill.lines[].cost_code_id
    integer | null
  • bill.lines[].cost_type_id
    integer | null
  • bill.lines[].equipment_id
    integer | null
  • bill.lines[].commitment_line_item_id
    integer | null
  • bill.lines[].quantity
    string | null
  • bill.lines[].unit_price
    string | null
  • bill.lines[].use_tax
    boolean
    Omitted 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_1099
    boolean
  • bill.lines[].tax_category
    string | null
    One of: material, fixture, labor, equipment, null.
  • bill.lines[].dimension_value_ids
    array | null
    User-defined dimension values (AcctDimensionValue ids), at most one per dimension; see oas-dimensions.json.

Response · 201 · object

  • id
    integerrequired
  • number
    stringrequired
  • kind
    stringrequired
    One of: bill, credit.
  • status
    stringrequired
    One of: draft, pending_approval, posted, void.
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • entity_id
    integerrequired
  • invoice_number
    string | nullrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • term_id
    integer | nullrequired
  • discount_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • discount_date
    string | null (date)required
  • memo
    string | nullrequired
  • total
    stringrequired
    Money, 2 dp
  • retainage_amount
    stringrequired
    Money, 2 dp
  • use_tax_amount
    stringrequired
    Money, 2 dp
  • tax_code_id
    integer | nullrequired
  • open_amount
    stringrequired
    Money, 2 dp
  • retainage_open
    stringrequired
    Money, 2 dp
  • paid_amount
    stringrequired
    Money, 2 dp
  • retainage_released
    stringrequired
    Money, 2 dp
  • commitment_type
    string | nullrequired
  • commitment_id
    integer | nullrequired
  • requisition_id
    integer | nullrequired
  • direct_cost_id
    integer | nullrequired
  • pay_when_paid_pay_app_id
    integer | nullrequired
  • pay_when_paid_mode
    string | nullrequired
  • off_rent_date
    string | null (date)required
  • billed_through
    string | null (date)required
  • match
    object | nullrequired
  • hold_overrides
    object[]required
  • revision
    integerrequired
  • prepared_by_id
    integerrequired
  • last_edited_by_id
    integerrequired
  • contributor_ids
    integer[]required
    Every user who created or edited the bill. None of them may approve it, override its holds or release its payment.
  • submitted_at
    string | null (date-time)required
  • approved_at
    string | null (date-time)required
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • lines
    object[]required
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].description
    string | nullrequired
  • lines[].amount
    stringrequired
    Money, 2 dp
  • lines[].retainage_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].retainage_amount
    stringrequired
    Money, 2 dp
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].equipment_id
    integer | nullrequired
  • lines[].commitment_line_item_id
    integer | nullrequired
  • lines[].quantity
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].unit_price
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].use_tax
    booleanrequired
  • lines[].reportable_1099
    booleanrequired
  • lines[].tax_category
    string | nullrequired
    Contractor 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_ids
    array | nullrequired
    User-defined dimension values (AcctDimensionValue ids).
  • holds
    object[]required
  • holds[].code
    stringrequired
    Hold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
  • holds[].message
    stringrequired
  • holds[].overridden
    booleanrequired
  • approvals_required
    integerrequired
  • route_preview
    stringrequired
  • approvals
    object[]required
  • approvals[].user_id
    integerrequired
  • approvals[].step
    integerrequired
  • approvals[].approved_at
    string (date-time)required
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].bill_id
    integerrequired
  • applications[].payment_id
    integer | nullrequired
  • applications[].credit_id
    integer | nullrequired
  • applications[].date
    string (date)required
  • applications[].amount
    stringrequired
    Money, 2 dp
  • applications[].discount
    stringrequired
    Money, 2 dp
  • applications[].withholding
    stringrequired
    Money, 2 dp
  • applications[].voided
    booleanrequired
  • retainage_releases
    object[]required
  • retainage_releases[].id
    integerrequired
  • retainage_releases[].date
    string (date)required
  • retainage_releases[].amount
    stringrequired
    Money, 2 dp
  • retainage_releases[].entry_id
    integerrequired
  • retainage_releases[].voided_at
    string | null (date)
    Effective void date; as-of aging counts the release before it.
  • retainage_releases[].void_entry_id
    integer | null
  • retainage_releases[].void_reason
    string | null

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)
  • 422Validation failed or the ledger refused the change

Example request

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • kind
    stringrequired
    One of: bill, credit.
  • status
    stringrequired
    One of: draft, pending_approval, posted, void.
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • entity_id
    integerrequired
  • invoice_number
    string | nullrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • term_id
    integer | nullrequired
  • discount_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • discount_date
    string | null (date)required
  • memo
    string | nullrequired
  • total
    stringrequired
    Money, 2 dp
  • retainage_amount
    stringrequired
    Money, 2 dp
  • use_tax_amount
    stringrequired
    Money, 2 dp
  • tax_code_id
    integer | nullrequired
  • open_amount
    stringrequired
    Money, 2 dp
  • retainage_open
    stringrequired
    Money, 2 dp
  • paid_amount
    stringrequired
    Money, 2 dp
  • retainage_released
    stringrequired
    Money, 2 dp
  • commitment_type
    string | nullrequired
  • commitment_id
    integer | nullrequired
  • requisition_id
    integer | nullrequired
  • direct_cost_id
    integer | nullrequired
  • pay_when_paid_pay_app_id
    integer | nullrequired
  • pay_when_paid_mode
    string | nullrequired
  • off_rent_date
    string | null (date)required
  • billed_through
    string | null (date)required
  • match
    object | nullrequired
  • hold_overrides
    object[]required
  • revision
    integerrequired
  • prepared_by_id
    integerrequired
  • last_edited_by_id
    integerrequired
  • contributor_ids
    integer[]required
    Every user who created or edited the bill. None of them may approve it, override its holds or release its payment.
  • submitted_at
    string | null (date-time)required
  • approved_at
    string | null (date-time)required
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • lines
    object[]required
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].description
    string | nullrequired
  • lines[].amount
    stringrequired
    Money, 2 dp
  • lines[].retainage_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].retainage_amount
    stringrequired
    Money, 2 dp
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].equipment_id
    integer | nullrequired
  • lines[].commitment_line_item_id
    integer | nullrequired
  • lines[].quantity
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].unit_price
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].use_tax
    booleanrequired
  • lines[].reportable_1099
    booleanrequired
  • lines[].tax_category
    string | nullrequired
    Contractor 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_ids
    array | nullrequired
    User-defined dimension values (AcctDimensionValue ids).
  • holds
    object[]required
  • holds[].code
    stringrequired
    Hold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
  • holds[].message
    stringrequired
  • holds[].overridden
    booleanrequired
  • approvals_required
    integerrequired
  • route_preview
    stringrequired
  • approvals
    object[]required
  • approvals[].user_id
    integerrequired
  • approvals[].step
    integerrequired
  • approvals[].approved_at
    string (date-time)required
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].bill_id
    integerrequired
  • applications[].payment_id
    integer | nullrequired
  • applications[].credit_id
    integer | nullrequired
  • applications[].date
    string (date)required
  • applications[].amount
    stringrequired
    Money, 2 dp
  • applications[].discount
    stringrequired
    Money, 2 dp
  • applications[].withholding
    stringrequired
    Money, 2 dp
  • applications[].voided
    booleanrequired
  • retainage_releases
    object[]required
  • retainage_releases[].id
    integerrequired
  • retainage_releases[].date
    string (date)required
  • retainage_releases[].amount
    stringrequired
    Money, 2 dp
  • retainage_releases[].entry_id
    integerrequired
  • retainage_releases[].voided_at
    string | null (date)
    Effective void date; as-of aging counts the release before it.
  • retainage_releases[].void_entry_id
    integer | null
  • retainage_releases[].void_reason
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

v1.0Implemented

Parameters

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

Request body

  • bill
    objectrequired
  • bill.expected_revision
    integerrequired
    Revision returned by the last bill read; required for every edit.
  • bill.kind
    string
  • bill.vendor_id
    integer
  • bill.entity_id
    integer | null
  • bill.invoice_number
    string | null
  • bill.invoice_date
    string (date)
  • bill.posting_date
    string (date)
  • bill.due_date
    string (date)
  • bill.term_id
    integer | null
  • bill.memo
    string | null
  • bill.retainage_percent
    string | null
  • bill.tax_code_id
    integer | null
  • bill.commitment_type
    string | null
  • bill.commitment_id
    integer | null
  • bill.pay_when_paid_pay_app_id
    integer | null
  • bill.pay_when_paid_mode
    string | null
  • bill.off_rent_date
    string | null (date)
  • bill.billed_through
    string | null (date)
  • bill.duplicate_override_reason
    string | null
  • bill.inactive_vendor_override_reason
    string | null
    Bill 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.lines
    object[]
  • bill.lines[].account_id
    integerrequired
  • bill.lines[].amount
    stringrequired
  • bill.lines[].description
    string | null
  • bill.lines[].retainage_percent
    string | null
  • bill.lines[].retainage_amount
    string | null
    Explicit retainage (at most the line amount); overrides retainage_percent.
  • bill.lines[].project_id
    integer | null
  • bill.lines[].cost_code_id
    integer | null
  • bill.lines[].cost_type_id
    integer | null
  • bill.lines[].equipment_id
    integer | null
  • bill.lines[].commitment_line_item_id
    integer | null
  • bill.lines[].quantity
    string | null
  • bill.lines[].unit_price
    string | null
  • bill.lines[].use_tax
    boolean
    Omitted 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_1099
    boolean
  • bill.lines[].tax_category
    string | null
    One of: material, fixture, labor, equipment, null.
  • bill.lines[].dimension_value_ids
    array | null
    User-defined dimension values (AcctDimensionValue ids), at most one per dimension; see oas-dimensions.json.

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • kind
    stringrequired
    One of: bill, credit.
  • status
    stringrequired
    One of: draft, pending_approval, posted, void.
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • entity_id
    integerrequired
  • invoice_number
    string | nullrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • term_id
    integer | nullrequired
  • discount_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • discount_date
    string | null (date)required
  • memo
    string | nullrequired
  • total
    stringrequired
    Money, 2 dp
  • retainage_amount
    stringrequired
    Money, 2 dp
  • use_tax_amount
    stringrequired
    Money, 2 dp
  • tax_code_id
    integer | nullrequired
  • open_amount
    stringrequired
    Money, 2 dp
  • retainage_open
    stringrequired
    Money, 2 dp
  • paid_amount
    stringrequired
    Money, 2 dp
  • retainage_released
    stringrequired
    Money, 2 dp
  • commitment_type
    string | nullrequired
  • commitment_id
    integer | nullrequired
  • requisition_id
    integer | nullrequired
  • direct_cost_id
    integer | nullrequired
  • pay_when_paid_pay_app_id
    integer | nullrequired
  • pay_when_paid_mode
    string | nullrequired
  • off_rent_date
    string | null (date)required
  • billed_through
    string | null (date)required
  • match
    object | nullrequired
  • hold_overrides
    object[]required
  • revision
    integerrequired
  • prepared_by_id
    integerrequired
  • last_edited_by_id
    integerrequired
  • contributor_ids
    integer[]required
    Every user who created or edited the bill. None of them may approve it, override its holds or release its payment.
  • submitted_at
    string | null (date-time)required
  • approved_at
    string | null (date-time)required
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • lines
    object[]required
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].description
    string | nullrequired
  • lines[].amount
    stringrequired
    Money, 2 dp
  • lines[].retainage_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].retainage_amount
    stringrequired
    Money, 2 dp
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].equipment_id
    integer | nullrequired
  • lines[].commitment_line_item_id
    integer | nullrequired
  • lines[].quantity
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].unit_price
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].use_tax
    booleanrequired
  • lines[].reportable_1099
    booleanrequired
  • lines[].tax_category
    string | nullrequired
    Contractor 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_ids
    array | nullrequired
    User-defined dimension values (AcctDimensionValue ids).
  • holds
    object[]required
  • holds[].code
    stringrequired
    Hold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
  • holds[].message
    stringrequired
  • holds[].overridden
    booleanrequired
  • approvals_required
    integerrequired
  • route_preview
    stringrequired
  • approvals
    object[]required
  • approvals[].user_id
    integerrequired
  • approvals[].step
    integerrequired
  • approvals[].approved_at
    string (date-time)required
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].bill_id
    integerrequired
  • applications[].payment_id
    integer | nullrequired
  • applications[].credit_id
    integer | nullrequired
  • applications[].date
    string (date)required
  • applications[].amount
    stringrequired
    Money, 2 dp
  • applications[].discount
    stringrequired
    Money, 2 dp
  • applications[].withholding
    stringrequired
    Money, 2 dp
  • applications[].voided
    booleanrequired
  • retainage_releases
    object[]required
  • retainage_releases[].id
    integerrequired
  • retainage_releases[].date
    string (date)required
  • retainage_releases[].amount
    stringrequired
    Money, 2 dp
  • retainage_releases[].entry_id
    integerrequired
  • retainage_releases[].voided_at
    string | null (date)
    Effective void date; as-of aging counts the release before it.
  • retainage_releases[].void_entry_id
    integer | null
  • retainage_releases[].void_reason
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (stale_revision or duplicate_suspected)
  • 422Validation failed or the ledger refused the change

Example request

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

v1.0Implemented

Parameters

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

Response · 204

No response body.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed or the ledger refused the change

Example request

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

Apply a vendor credit to a bill

The path id is the credit. Same vendor, both posted; no GL effect. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • application
    objectrequired
  • application.bill_id
    integerrequired
  • application.amount
    stringrequired
  • application.date
    string (date)required

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • kind
    stringrequired
    One of: bill, credit.
  • status
    stringrequired
    One of: draft, pending_approval, posted, void.
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • entity_id
    integerrequired
  • invoice_number
    string | nullrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • term_id
    integer | nullrequired
  • discount_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • discount_date
    string | null (date)required
  • memo
    string | nullrequired
  • total
    stringrequired
    Money, 2 dp
  • retainage_amount
    stringrequired
    Money, 2 dp
  • use_tax_amount
    stringrequired
    Money, 2 dp
  • tax_code_id
    integer | nullrequired
  • open_amount
    stringrequired
    Money, 2 dp
  • retainage_open
    stringrequired
    Money, 2 dp
  • paid_amount
    stringrequired
    Money, 2 dp
  • retainage_released
    stringrequired
    Money, 2 dp
  • commitment_type
    string | nullrequired
  • commitment_id
    integer | nullrequired
  • requisition_id
    integer | nullrequired
  • direct_cost_id
    integer | nullrequired
  • pay_when_paid_pay_app_id
    integer | nullrequired
  • pay_when_paid_mode
    string | nullrequired
  • off_rent_date
    string | null (date)required
  • billed_through
    string | null (date)required
  • match
    object | nullrequired
  • hold_overrides
    object[]required
  • revision
    integerrequired
  • prepared_by_id
    integerrequired
  • last_edited_by_id
    integerrequired
  • contributor_ids
    integer[]required
    Every user who created or edited the bill. None of them may approve it, override its holds or release its payment.
  • submitted_at
    string | null (date-time)required
  • approved_at
    string | null (date-time)required
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • lines
    object[]required
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].description
    string | nullrequired
  • lines[].amount
    stringrequired
    Money, 2 dp
  • lines[].retainage_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].retainage_amount
    stringrequired
    Money, 2 dp
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].equipment_id
    integer | nullrequired
  • lines[].commitment_line_item_id
    integer | nullrequired
  • lines[].quantity
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].unit_price
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].use_tax
    booleanrequired
  • lines[].reportable_1099
    booleanrequired
  • lines[].tax_category
    string | nullrequired
    Contractor 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_ids
    array | nullrequired
    User-defined dimension values (AcctDimensionValue ids).
  • holds
    object[]required
  • holds[].code
    stringrequired
    Hold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
  • holds[].message
    stringrequired
  • holds[].overridden
    booleanrequired
  • approvals_required
    integerrequired
  • route_preview
    stringrequired
  • approvals
    object[]required
  • approvals[].user_id
    integerrequired
  • approvals[].step
    integerrequired
  • approvals[].approved_at
    string (date-time)required
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].bill_id
    integerrequired
  • applications[].payment_id
    integer | nullrequired
  • applications[].credit_id
    integer | nullrequired
  • applications[].date
    string (date)required
  • applications[].amount
    stringrequired
    Money, 2 dp
  • applications[].discount
    stringrequired
    Money, 2 dp
  • applications[].withholding
    stringrequired
    Money, 2 dp
  • applications[].voided
    booleanrequired
  • retainage_releases
    object[]required
  • retainage_releases[].id
    integerrequired
  • retainage_releases[].date
    string (date)required
  • retainage_releases[].amount
    stringrequired
    Money, 2 dp
  • retainage_releases[].entry_id
    integerrequired
  • retainage_releases[].voided_at
    string | null (date)
    Effective void date; as-of aging counts the release before it.
  • retainage_releases[].void_entry_id
    integer | null
  • retainage_releases[].void_reason
    string | null

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)
  • 422Validation failed or the ledger refused the change

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • approve
    object
  • approve.reason
    string
    Required 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

  • id
    integerrequired
  • number
    stringrequired
  • kind
    stringrequired
    One of: bill, credit.
  • status
    stringrequired
    One of: draft, pending_approval, posted, void.
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • entity_id
    integerrequired
  • invoice_number
    string | nullrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • term_id
    integer | nullrequired
  • discount_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • discount_date
    string | null (date)required
  • memo
    string | nullrequired
  • total
    stringrequired
    Money, 2 dp
  • retainage_amount
    stringrequired
    Money, 2 dp
  • use_tax_amount
    stringrequired
    Money, 2 dp
  • tax_code_id
    integer | nullrequired
  • open_amount
    stringrequired
    Money, 2 dp
  • retainage_open
    stringrequired
    Money, 2 dp
  • paid_amount
    stringrequired
    Money, 2 dp
  • retainage_released
    stringrequired
    Money, 2 dp
  • commitment_type
    string | nullrequired
  • commitment_id
    integer | nullrequired
  • requisition_id
    integer | nullrequired
  • direct_cost_id
    integer | nullrequired
  • pay_when_paid_pay_app_id
    integer | nullrequired
  • pay_when_paid_mode
    string | nullrequired
  • off_rent_date
    string | null (date)required
  • billed_through
    string | null (date)required
  • match
    object | nullrequired
  • hold_overrides
    object[]required
  • revision
    integerrequired
  • prepared_by_id
    integerrequired
  • last_edited_by_id
    integerrequired
  • contributor_ids
    integer[]required
    Every user who created or edited the bill. None of them may approve it, override its holds or release its payment.
  • submitted_at
    string | null (date-time)required
  • approved_at
    string | null (date-time)required
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • lines
    object[]required
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].description
    string | nullrequired
  • lines[].amount
    stringrequired
    Money, 2 dp
  • lines[].retainage_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].retainage_amount
    stringrequired
    Money, 2 dp
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].equipment_id
    integer | nullrequired
  • lines[].commitment_line_item_id
    integer | nullrequired
  • lines[].quantity
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].unit_price
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].use_tax
    booleanrequired
  • lines[].reportable_1099
    booleanrequired
  • lines[].tax_category
    string | nullrequired
    Contractor 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_ids
    array | nullrequired
    User-defined dimension values (AcctDimensionValue ids).
  • holds
    object[]required
  • holds[].code
    stringrequired
    Hold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
  • holds[].message
    stringrequired
  • holds[].overridden
    booleanrequired
  • approvals_required
    integerrequired
  • route_preview
    stringrequired
  • approvals
    object[]required
  • approvals[].user_id
    integerrequired
  • approvals[].step
    integerrequired
  • approvals[].approved_at
    string (date-time)required
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].bill_id
    integerrequired
  • applications[].payment_id
    integer | nullrequired
  • applications[].credit_id
    integer | nullrequired
  • applications[].date
    string (date)required
  • applications[].amount
    stringrequired
    Money, 2 dp
  • applications[].discount
    stringrequired
    Money, 2 dp
  • applications[].withholding
    stringrequired
    Money, 2 dp
  • applications[].voided
    booleanrequired
  • retainage_releases
    object[]required
  • retainage_releases[].id
    integerrequired
  • retainage_releases[].date
    string (date)required
  • retainage_releases[].amount
    stringrequired
    Money, 2 dp
  • retainage_releases[].entry_id
    integerrequired
  • retainage_releases[].voided_at
    string | null (date)
    Effective void date; as-of aging counts the release before it.
  • retainage_releases[].void_entry_id
    integer | null
  • retainage_releases[].void_reason
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)
  • 422Validation failed or the ledger refused the change

Example request

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

List attachments on a bill

Oldest first. Needs view_ledger and the parent's entity scope. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • doc_type
    stringrequired
    One 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_id
    integerrequired
  • name
    stringrequired
  • content_type
    stringrequired
  • size_bytes
    integerrequired
  • sha256
    stringrequired
  • uploaded_by
    objectrequired
  • uploaded_by.id
    integerrequired
  • uploaded_by.name
    string | nullrequired
  • created_at
    string (date-time)required
  • download_url
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • file
    string (binary)required

Response · 201 · object

  • id
    integerrequired
  • doc_type
    stringrequired
    One 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_id
    integerrequired
  • name
    stringrequired
  • content_type
    stringrequired
  • size_bytes
    integerrequired
  • sha256
    stringrequired
  • uploaded_by
    objectrequired
  • uploaded_by.id
    integerrequired
  • uploaded_by.name
    string | nullrequired
  • created_at
    string (date-time)required
  • download_url
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Idempotency-Key reused for a different request or still in progress
  • 413Request body too large
  • 422Missing file, empty file, too large, or a type that is not allowed

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • override
    objectrequired
  • override.code
    stringrequired
  • override.reason
    stringrequired
  • override.expires_at
    string | null (date)

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • kind
    stringrequired
    One of: bill, credit.
  • status
    stringrequired
    One of: draft, pending_approval, posted, void.
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • entity_id
    integerrequired
  • invoice_number
    string | nullrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • term_id
    integer | nullrequired
  • discount_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • discount_date
    string | null (date)required
  • memo
    string | nullrequired
  • total
    stringrequired
    Money, 2 dp
  • retainage_amount
    stringrequired
    Money, 2 dp
  • use_tax_amount
    stringrequired
    Money, 2 dp
  • tax_code_id
    integer | nullrequired
  • open_amount
    stringrequired
    Money, 2 dp
  • retainage_open
    stringrequired
    Money, 2 dp
  • paid_amount
    stringrequired
    Money, 2 dp
  • retainage_released
    stringrequired
    Money, 2 dp
  • commitment_type
    string | nullrequired
  • commitment_id
    integer | nullrequired
  • requisition_id
    integer | nullrequired
  • direct_cost_id
    integer | nullrequired
  • pay_when_paid_pay_app_id
    integer | nullrequired
  • pay_when_paid_mode
    string | nullrequired
  • off_rent_date
    string | null (date)required
  • billed_through
    string | null (date)required
  • match
    object | nullrequired
  • hold_overrides
    object[]required
  • revision
    integerrequired
  • prepared_by_id
    integerrequired
  • last_edited_by_id
    integerrequired
  • contributor_ids
    integer[]required
    Every user who created or edited the bill. None of them may approve it, override its holds or release its payment.
  • submitted_at
    string | null (date-time)required
  • approved_at
    string | null (date-time)required
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • lines
    object[]required
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].description
    string | nullrequired
  • lines[].amount
    stringrequired
    Money, 2 dp
  • lines[].retainage_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].retainage_amount
    stringrequired
    Money, 2 dp
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].equipment_id
    integer | nullrequired
  • lines[].commitment_line_item_id
    integer | nullrequired
  • lines[].quantity
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].unit_price
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].use_tax
    booleanrequired
  • lines[].reportable_1099
    booleanrequired
  • lines[].tax_category
    string | nullrequired
    Contractor 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_ids
    array | nullrequired
    User-defined dimension values (AcctDimensionValue ids).
  • holds
    object[]required
  • holds[].code
    stringrequired
    Hold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
  • holds[].message
    stringrequired
  • holds[].overridden
    booleanrequired
  • approvals_required
    integerrequired
  • route_preview
    stringrequired
  • approvals
    object[]required
  • approvals[].user_id
    integerrequired
  • approvals[].step
    integerrequired
  • approvals[].approved_at
    string (date-time)required
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].bill_id
    integerrequired
  • applications[].payment_id
    integer | nullrequired
  • applications[].credit_id
    integer | nullrequired
  • applications[].date
    string (date)required
  • applications[].amount
    stringrequired
    Money, 2 dp
  • applications[].discount
    stringrequired
    Money, 2 dp
  • applications[].withholding
    stringrequired
    Money, 2 dp
  • applications[].voided
    booleanrequired
  • retainage_releases
    object[]required
  • retainage_releases[].id
    integerrequired
  • retainage_releases[].date
    string (date)required
  • retainage_releases[].amount
    stringrequired
    Money, 2 dp
  • retainage_releases[].entry_id
    integerrequired
  • retainage_releases[].voided_at
    string | null (date)
    Effective void date; as-of aging counts the release before it.
  • retainage_releases[].void_entry_id
    integer | null
  • retainage_releases[].void_reason
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)
  • 422Validation failed or the ledger refused the change

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • reject
    objectrequired
  • reject.reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • kind
    stringrequired
    One of: bill, credit.
  • status
    stringrequired
    One of: draft, pending_approval, posted, void.
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • entity_id
    integerrequired
  • invoice_number
    string | nullrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • term_id
    integer | nullrequired
  • discount_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • discount_date
    string | null (date)required
  • memo
    string | nullrequired
  • total
    stringrequired
    Money, 2 dp
  • retainage_amount
    stringrequired
    Money, 2 dp
  • use_tax_amount
    stringrequired
    Money, 2 dp
  • tax_code_id
    integer | nullrequired
  • open_amount
    stringrequired
    Money, 2 dp
  • retainage_open
    stringrequired
    Money, 2 dp
  • paid_amount
    stringrequired
    Money, 2 dp
  • retainage_released
    stringrequired
    Money, 2 dp
  • commitment_type
    string | nullrequired
  • commitment_id
    integer | nullrequired
  • requisition_id
    integer | nullrequired
  • direct_cost_id
    integer | nullrequired
  • pay_when_paid_pay_app_id
    integer | nullrequired
  • pay_when_paid_mode
    string | nullrequired
  • off_rent_date
    string | null (date)required
  • billed_through
    string | null (date)required
  • match
    object | nullrequired
  • hold_overrides
    object[]required
  • revision
    integerrequired
  • prepared_by_id
    integerrequired
  • last_edited_by_id
    integerrequired
  • contributor_ids
    integer[]required
    Every user who created or edited the bill. None of them may approve it, override its holds or release its payment.
  • submitted_at
    string | null (date-time)required
  • approved_at
    string | null (date-time)required
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • lines
    object[]required
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].description
    string | nullrequired
  • lines[].amount
    stringrequired
    Money, 2 dp
  • lines[].retainage_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].retainage_amount
    stringrequired
    Money, 2 dp
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].equipment_id
    integer | nullrequired
  • lines[].commitment_line_item_id
    integer | nullrequired
  • lines[].quantity
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].unit_price
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].use_tax
    booleanrequired
  • lines[].reportable_1099
    booleanrequired
  • lines[].tax_category
    string | nullrequired
    Contractor 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_ids
    array | nullrequired
    User-defined dimension values (AcctDimensionValue ids).
  • holds
    object[]required
  • holds[].code
    stringrequired
    Hold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
  • holds[].message
    stringrequired
  • holds[].overridden
    booleanrequired
  • approvals_required
    integerrequired
  • route_preview
    stringrequired
  • approvals
    object[]required
  • approvals[].user_id
    integerrequired
  • approvals[].step
    integerrequired
  • approvals[].approved_at
    string (date-time)required
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].bill_id
    integerrequired
  • applications[].payment_id
    integer | nullrequired
  • applications[].credit_id
    integer | nullrequired
  • applications[].date
    string (date)required
  • applications[].amount
    stringrequired
    Money, 2 dp
  • applications[].discount
    stringrequired
    Money, 2 dp
  • applications[].withholding
    stringrequired
    Money, 2 dp
  • applications[].voided
    booleanrequired
  • retainage_releases
    object[]required
  • retainage_releases[].id
    integerrequired
  • retainage_releases[].date
    string (date)required
  • retainage_releases[].amount
    stringrequired
    Money, 2 dp
  • retainage_releases[].entry_id
    integerrequired
  • retainage_releases[].voided_at
    string | null (date)
    Effective void date; as-of aging counts the release before it.
  • retainage_releases[].void_entry_id
    integer | null
  • retainage_releases[].void_reason
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, or wrong company
  • 404Not found in this company
  • 422Validation failed

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • release
    objectrequired
  • release.date
    string (date)required
  • release.amount
    string
  • release.final
    boolean
  • release.owner_released
    boolean
  • release.lower_tier_parties
    string[]

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • kind
    stringrequired
    One of: bill, credit.
  • status
    stringrequired
    One of: draft, pending_approval, posted, void.
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • entity_id
    integerrequired
  • invoice_number
    string | nullrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • term_id
    integer | nullrequired
  • discount_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • discount_date
    string | null (date)required
  • memo
    string | nullrequired
  • total
    stringrequired
    Money, 2 dp
  • retainage_amount
    stringrequired
    Money, 2 dp
  • use_tax_amount
    stringrequired
    Money, 2 dp
  • tax_code_id
    integer | nullrequired
  • open_amount
    stringrequired
    Money, 2 dp
  • retainage_open
    stringrequired
    Money, 2 dp
  • paid_amount
    stringrequired
    Money, 2 dp
  • retainage_released
    stringrequired
    Money, 2 dp
  • commitment_type
    string | nullrequired
  • commitment_id
    integer | nullrequired
  • requisition_id
    integer | nullrequired
  • direct_cost_id
    integer | nullrequired
  • pay_when_paid_pay_app_id
    integer | nullrequired
  • pay_when_paid_mode
    string | nullrequired
  • off_rent_date
    string | null (date)required
  • billed_through
    string | null (date)required
  • match
    object | nullrequired
  • hold_overrides
    object[]required
  • revision
    integerrequired
  • prepared_by_id
    integerrequired
  • last_edited_by_id
    integerrequired
  • contributor_ids
    integer[]required
    Every user who created or edited the bill. None of them may approve it, override its holds or release its payment.
  • submitted_at
    string | null (date-time)required
  • approved_at
    string | null (date-time)required
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • lines
    object[]required
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].description
    string | nullrequired
  • lines[].amount
    stringrequired
    Money, 2 dp
  • lines[].retainage_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].retainage_amount
    stringrequired
    Money, 2 dp
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].equipment_id
    integer | nullrequired
  • lines[].commitment_line_item_id
    integer | nullrequired
  • lines[].quantity
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].unit_price
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].use_tax
    booleanrequired
  • lines[].reportable_1099
    booleanrequired
  • lines[].tax_category
    string | nullrequired
    Contractor 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_ids
    array | nullrequired
    User-defined dimension values (AcctDimensionValue ids).
  • holds
    object[]required
  • holds[].code
    stringrequired
    Hold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
  • holds[].message
    stringrequired
  • holds[].overridden
    booleanrequired
  • approvals_required
    integerrequired
  • route_preview
    stringrequired
  • approvals
    object[]required
  • approvals[].user_id
    integerrequired
  • approvals[].step
    integerrequired
  • approvals[].approved_at
    string (date-time)required
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].bill_id
    integerrequired
  • applications[].payment_id
    integer | nullrequired
  • applications[].credit_id
    integer | nullrequired
  • applications[].date
    string (date)required
  • applications[].amount
    stringrequired
    Money, 2 dp
  • applications[].discount
    stringrequired
    Money, 2 dp
  • applications[].withholding
    stringrequired
    Money, 2 dp
  • applications[].voided
    booleanrequired
  • retainage_releases
    object[]required
  • retainage_releases[].id
    integerrequired
  • retainage_releases[].date
    string (date)required
  • retainage_releases[].amount
    stringrequired
    Money, 2 dp
  • retainage_releases[].entry_id
    integerrequired
  • retainage_releases[].voided_at
    string | null (date)
    Effective void date; as-of aging counts the release before it.
  • retainage_releases[].void_entry_id
    integer | null
  • retainage_releases[].void_reason
    string | null

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)
  • 422Validation failed or the ledger refused the change

Example request

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

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • kind
    stringrequired
    One of: bill, credit.
  • status
    stringrequired
    One of: draft, pending_approval, posted, void.
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • entity_id
    integerrequired
  • invoice_number
    string | nullrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • term_id
    integer | nullrequired
  • discount_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • discount_date
    string | null (date)required
  • memo
    string | nullrequired
  • total
    stringrequired
    Money, 2 dp
  • retainage_amount
    stringrequired
    Money, 2 dp
  • use_tax_amount
    stringrequired
    Money, 2 dp
  • tax_code_id
    integer | nullrequired
  • open_amount
    stringrequired
    Money, 2 dp
  • retainage_open
    stringrequired
    Money, 2 dp
  • paid_amount
    stringrequired
    Money, 2 dp
  • retainage_released
    stringrequired
    Money, 2 dp
  • commitment_type
    string | nullrequired
  • commitment_id
    integer | nullrequired
  • requisition_id
    integer | nullrequired
  • direct_cost_id
    integer | nullrequired
  • pay_when_paid_pay_app_id
    integer | nullrequired
  • pay_when_paid_mode
    string | nullrequired
  • off_rent_date
    string | null (date)required
  • billed_through
    string | null (date)required
  • match
    object | nullrequired
  • hold_overrides
    object[]required
  • revision
    integerrequired
  • prepared_by_id
    integerrequired
  • last_edited_by_id
    integerrequired
  • contributor_ids
    integer[]required
    Every user who created or edited the bill. None of them may approve it, override its holds or release its payment.
  • submitted_at
    string | null (date-time)required
  • approved_at
    string | null (date-time)required
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • lines
    object[]required
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].description
    string | nullrequired
  • lines[].amount
    stringrequired
    Money, 2 dp
  • lines[].retainage_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].retainage_amount
    stringrequired
    Money, 2 dp
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].equipment_id
    integer | nullrequired
  • lines[].commitment_line_item_id
    integer | nullrequired
  • lines[].quantity
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].unit_price
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].use_tax
    booleanrequired
  • lines[].reportable_1099
    booleanrequired
  • lines[].tax_category
    string | nullrequired
    Contractor 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_ids
    array | nullrequired
    User-defined dimension values (AcctDimensionValue ids).
  • holds
    object[]required
  • holds[].code
    stringrequired
    Hold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
  • holds[].message
    stringrequired
  • holds[].overridden
    booleanrequired
  • approvals_required
    integerrequired
  • route_preview
    stringrequired
  • approvals
    object[]required
  • approvals[].user_id
    integerrequired
  • approvals[].step
    integerrequired
  • approvals[].approved_at
    string (date-time)required
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].bill_id
    integerrequired
  • applications[].payment_id
    integer | nullrequired
  • applications[].credit_id
    integer | nullrequired
  • applications[].date
    string (date)required
  • applications[].amount
    stringrequired
    Money, 2 dp
  • applications[].discount
    stringrequired
    Money, 2 dp
  • applications[].withholding
    stringrequired
    Money, 2 dp
  • applications[].voided
    booleanrequired
  • retainage_releases
    object[]required
  • retainage_releases[].id
    integerrequired
  • retainage_releases[].date
    string (date)required
  • retainage_releases[].amount
    stringrequired
    Money, 2 dp
  • retainage_releases[].entry_id
    integerrequired
  • retainage_releases[].voided_at
    string | null (date)
    Effective void date; as-of aging counts the release before it.
  • retainage_releases[].void_entry_id
    integer | null
  • retainage_releases[].void_reason
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed

Example request

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

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • kind
    stringrequired
    One of: bill, credit.
  • status
    stringrequired
    One of: draft, pending_approval, posted, void.
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • entity_id
    integerrequired
  • invoice_number
    string | nullrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • term_id
    integer | nullrequired
  • discount_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • discount_date
    string | null (date)required
  • memo
    string | nullrequired
  • total
    stringrequired
    Money, 2 dp
  • retainage_amount
    stringrequired
    Money, 2 dp
  • use_tax_amount
    stringrequired
    Money, 2 dp
  • tax_code_id
    integer | nullrequired
  • open_amount
    stringrequired
    Money, 2 dp
  • retainage_open
    stringrequired
    Money, 2 dp
  • paid_amount
    stringrequired
    Money, 2 dp
  • retainage_released
    stringrequired
    Money, 2 dp
  • commitment_type
    string | nullrequired
  • commitment_id
    integer | nullrequired
  • requisition_id
    integer | nullrequired
  • direct_cost_id
    integer | nullrequired
  • pay_when_paid_pay_app_id
    integer | nullrequired
  • pay_when_paid_mode
    string | nullrequired
  • off_rent_date
    string | null (date)required
  • billed_through
    string | null (date)required
  • match
    object | nullrequired
  • hold_overrides
    object[]required
  • revision
    integerrequired
  • prepared_by_id
    integerrequired
  • last_edited_by_id
    integerrequired
  • contributor_ids
    integer[]required
    Every user who created or edited the bill. None of them may approve it, override its holds or release its payment.
  • submitted_at
    string | null (date-time)required
  • approved_at
    string | null (date-time)required
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • lines
    object[]required
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].description
    string | nullrequired
  • lines[].amount
    stringrequired
    Money, 2 dp
  • lines[].retainage_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].retainage_amount
    stringrequired
    Money, 2 dp
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].equipment_id
    integer | nullrequired
  • lines[].commitment_line_item_id
    integer | nullrequired
  • lines[].quantity
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].unit_price
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].use_tax
    booleanrequired
  • lines[].reportable_1099
    booleanrequired
  • lines[].tax_category
    string | nullrequired
    Contractor 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_ids
    array | nullrequired
    User-defined dimension values (AcctDimensionValue ids).
  • holds
    object[]required
  • holds[].code
    stringrequired
    Hold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
  • holds[].message
    stringrequired
  • holds[].overridden
    booleanrequired
  • approvals_required
    integerrequired
  • route_preview
    stringrequired
  • approvals
    object[]required
  • approvals[].user_id
    integerrequired
  • approvals[].step
    integerrequired
  • approvals[].approved_at
    string (date-time)required
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].bill_id
    integerrequired
  • applications[].payment_id
    integer | nullrequired
  • applications[].credit_id
    integer | nullrequired
  • applications[].date
    string (date)required
  • applications[].amount
    stringrequired
    Money, 2 dp
  • applications[].discount
    stringrequired
    Money, 2 dp
  • applications[].withholding
    stringrequired
    Money, 2 dp
  • applications[].voided
    booleanrequired
  • retainage_releases
    object[]required
  • retainage_releases[].id
    integerrequired
  • retainage_releases[].date
    string (date)required
  • retainage_releases[].amount
    stringrequired
    Money, 2 dp
  • retainage_releases[].entry_id
    integerrequired
  • retainage_releases[].voided_at
    string | null (date)
    Effective void date; as-of aging counts the release before it.
  • retainage_releases[].void_entry_id
    integer | null
  • retainage_releases[].void_reason
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)
  • 422Validation failed or the ledger refused the change

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • application
    objectrequired
  • application.application_id
    integerrequired
  • application.date
    string (date)required

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • kind
    stringrequired
    One of: bill, credit.
  • status
    stringrequired
    One of: draft, pending_approval, posted, void.
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • entity_id
    integerrequired
  • invoice_number
    string | nullrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • term_id
    integer | nullrequired
  • discount_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • discount_date
    string | null (date)required
  • memo
    string | nullrequired
  • total
    stringrequired
    Money, 2 dp
  • retainage_amount
    stringrequired
    Money, 2 dp
  • use_tax_amount
    stringrequired
    Money, 2 dp
  • tax_code_id
    integer | nullrequired
  • open_amount
    stringrequired
    Money, 2 dp
  • retainage_open
    stringrequired
    Money, 2 dp
  • paid_amount
    stringrequired
    Money, 2 dp
  • retainage_released
    stringrequired
    Money, 2 dp
  • commitment_type
    string | nullrequired
  • commitment_id
    integer | nullrequired
  • requisition_id
    integer | nullrequired
  • direct_cost_id
    integer | nullrequired
  • pay_when_paid_pay_app_id
    integer | nullrequired
  • pay_when_paid_mode
    string | nullrequired
  • off_rent_date
    string | null (date)required
  • billed_through
    string | null (date)required
  • match
    object | nullrequired
  • hold_overrides
    object[]required
  • revision
    integerrequired
  • prepared_by_id
    integerrequired
  • last_edited_by_id
    integerrequired
  • contributor_ids
    integer[]required
    Every user who created or edited the bill. None of them may approve it, override its holds or release its payment.
  • submitted_at
    string | null (date-time)required
  • approved_at
    string | null (date-time)required
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • lines
    object[]required
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].description
    string | nullrequired
  • lines[].amount
    stringrequired
    Money, 2 dp
  • lines[].retainage_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].retainage_amount
    stringrequired
    Money, 2 dp
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].equipment_id
    integer | nullrequired
  • lines[].commitment_line_item_id
    integer | nullrequired
  • lines[].quantity
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].unit_price
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].use_tax
    booleanrequired
  • lines[].reportable_1099
    booleanrequired
  • lines[].tax_category
    string | nullrequired
    Contractor 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_ids
    array | nullrequired
    User-defined dimension values (AcctDimensionValue ids).
  • holds
    object[]required
  • holds[].code
    stringrequired
    Hold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
  • holds[].message
    stringrequired
  • holds[].overridden
    booleanrequired
  • approvals_required
    integerrequired
  • route_preview
    stringrequired
  • approvals
    object[]required
  • approvals[].user_id
    integerrequired
  • approvals[].step
    integerrequired
  • approvals[].approved_at
    string (date-time)required
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].bill_id
    integerrequired
  • applications[].payment_id
    integer | nullrequired
  • applications[].credit_id
    integer | nullrequired
  • applications[].date
    string (date)required
  • applications[].amount
    stringrequired
    Money, 2 dp
  • applications[].discount
    stringrequired
    Money, 2 dp
  • applications[].withholding
    stringrequired
    Money, 2 dp
  • applications[].voided
    booleanrequired
  • retainage_releases
    object[]required
  • retainage_releases[].id
    integerrequired
  • retainage_releases[].date
    string (date)required
  • retainage_releases[].amount
    stringrequired
    Money, 2 dp
  • retainage_releases[].entry_id
    integerrequired
  • retainage_releases[].voided_at
    string | null (date)
    Effective void date; as-of aging counts the release before it.
  • retainage_releases[].void_entry_id
    integer | null
  • retainage_releases[].void_reason
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed or the ledger refused the change

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • void
    objectrequired
  • void.date
    string (date)required
  • void.reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • kind
    stringrequired
    One of: bill, credit.
  • status
    stringrequired
    One of: draft, pending_approval, posted, void.
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • entity_id
    integerrequired
  • invoice_number
    string | nullrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • term_id
    integer | nullrequired
  • discount_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • discount_date
    string | null (date)required
  • memo
    string | nullrequired
  • total
    stringrequired
    Money, 2 dp
  • retainage_amount
    stringrequired
    Money, 2 dp
  • use_tax_amount
    stringrequired
    Money, 2 dp
  • tax_code_id
    integer | nullrequired
  • open_amount
    stringrequired
    Money, 2 dp
  • retainage_open
    stringrequired
    Money, 2 dp
  • paid_amount
    stringrequired
    Money, 2 dp
  • retainage_released
    stringrequired
    Money, 2 dp
  • commitment_type
    string | nullrequired
  • commitment_id
    integer | nullrequired
  • requisition_id
    integer | nullrequired
  • direct_cost_id
    integer | nullrequired
  • pay_when_paid_pay_app_id
    integer | nullrequired
  • pay_when_paid_mode
    string | nullrequired
  • off_rent_date
    string | null (date)required
  • billed_through
    string | null (date)required
  • match
    object | nullrequired
  • hold_overrides
    object[]required
  • revision
    integerrequired
  • prepared_by_id
    integerrequired
  • last_edited_by_id
    integerrequired
  • contributor_ids
    integer[]required
    Every user who created or edited the bill. None of them may approve it, override its holds or release its payment.
  • submitted_at
    string | null (date-time)required
  • approved_at
    string | null (date-time)required
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • lines
    object[]required
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].description
    string | nullrequired
  • lines[].amount
    stringrequired
    Money, 2 dp
  • lines[].retainage_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].retainage_amount
    stringrequired
    Money, 2 dp
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].equipment_id
    integer | nullrequired
  • lines[].commitment_line_item_id
    integer | nullrequired
  • lines[].quantity
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].unit_price
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].use_tax
    booleanrequired
  • lines[].reportable_1099
    booleanrequired
  • lines[].tax_category
    string | nullrequired
    Contractor 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_ids
    array | nullrequired
    User-defined dimension values (AcctDimensionValue ids).
  • holds
    object[]required
  • holds[].code
    stringrequired
    Hold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
  • holds[].message
    stringrequired
  • holds[].overridden
    booleanrequired
  • approvals_required
    integerrequired
  • route_preview
    stringrequired
  • approvals
    object[]required
  • approvals[].user_id
    integerrequired
  • approvals[].step
    integerrequired
  • approvals[].approved_at
    string (date-time)required
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].bill_id
    integerrequired
  • applications[].payment_id
    integer | nullrequired
  • applications[].credit_id
    integer | nullrequired
  • applications[].date
    string (date)required
  • applications[].amount
    stringrequired
    Money, 2 dp
  • applications[].discount
    stringrequired
    Money, 2 dp
  • applications[].withholding
    stringrequired
    Money, 2 dp
  • applications[].voided
    booleanrequired
  • retainage_releases
    object[]required
  • retainage_releases[].id
    integerrequired
  • retainage_releases[].date
    string (date)required
  • retainage_releases[].amount
    stringrequired
    Money, 2 dp
  • retainage_releases[].entry_id
    integerrequired
  • retainage_releases[].voided_at
    string | null (date)
    Effective void date; as-of aging counts the release before it.
  • retainage_releases[].void_entry_id
    integer | null
  • retainage_releases[].void_reason
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)
  • 422Validation failed or the ledger refused the change

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • source
    objectrequired
  • source.requisition_id
    integer | null
  • source.direct_cost_id
    integer | null
  • source.invoice_date
    string (date)

Response · 201 · object

  • id
    integerrequired
  • number
    stringrequired
  • kind
    stringrequired
    One of: bill, credit.
  • status
    stringrequired
    One of: draft, pending_approval, posted, void.
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • entity_id
    integerrequired
  • invoice_number
    string | nullrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • term_id
    integer | nullrequired
  • discount_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • discount_date
    string | null (date)required
  • memo
    string | nullrequired
  • total
    stringrequired
    Money, 2 dp
  • retainage_amount
    stringrequired
    Money, 2 dp
  • use_tax_amount
    stringrequired
    Money, 2 dp
  • tax_code_id
    integer | nullrequired
  • open_amount
    stringrequired
    Money, 2 dp
  • retainage_open
    stringrequired
    Money, 2 dp
  • paid_amount
    stringrequired
    Money, 2 dp
  • retainage_released
    stringrequired
    Money, 2 dp
  • commitment_type
    string | nullrequired
  • commitment_id
    integer | nullrequired
  • requisition_id
    integer | nullrequired
  • direct_cost_id
    integer | nullrequired
  • pay_when_paid_pay_app_id
    integer | nullrequired
  • pay_when_paid_mode
    string | nullrequired
  • off_rent_date
    string | null (date)required
  • billed_through
    string | null (date)required
  • match
    object | nullrequired
  • hold_overrides
    object[]required
  • revision
    integerrequired
  • prepared_by_id
    integerrequired
  • last_edited_by_id
    integerrequired
  • contributor_ids
    integer[]required
    Every user who created or edited the bill. None of them may approve it, override its holds or release its payment.
  • submitted_at
    string | null (date-time)required
  • approved_at
    string | null (date-time)required
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • lines
    object[]required
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].description
    string | nullrequired
  • lines[].amount
    stringrequired
    Money, 2 dp
  • lines[].retainage_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].retainage_amount
    stringrequired
    Money, 2 dp
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].equipment_id
    integer | nullrequired
  • lines[].commitment_line_item_id
    integer | nullrequired
  • lines[].quantity
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].unit_price
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].use_tax
    booleanrequired
  • lines[].reportable_1099
    booleanrequired
  • lines[].tax_category
    string | nullrequired
    Contractor 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_ids
    array | nullrequired
    User-defined dimension values (AcctDimensionValue ids).
  • holds
    object[]required
  • holds[].code
    stringrequired
    Hold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
  • holds[].message
    stringrequired
  • holds[].overridden
    booleanrequired
  • approvals_required
    integerrequired
  • route_preview
    stringrequired
  • approvals
    object[]required
  • approvals[].user_id
    integerrequired
  • approvals[].step
    integerrequired
  • approvals[].approved_at
    string (date-time)required
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].bill_id
    integerrequired
  • applications[].payment_id
    integer | nullrequired
  • applications[].credit_id
    integer | nullrequired
  • applications[].date
    string (date)required
  • applications[].amount
    stringrequired
    Money, 2 dp
  • applications[].discount
    stringrequired
    Money, 2 dp
  • applications[].withholding
    stringrequired
    Money, 2 dp
  • applications[].voided
    booleanrequired
  • retainage_releases
    object[]required
  • retainage_releases[].id
    integerrequired
  • retainage_releases[].date
    string (date)required
  • retainage_releases[].amount
    stringrequired
    Money, 2 dp
  • retainage_releases[].entry_id
    integerrequired
  • retainage_releases[].voided_at
    string | null (date)
    Effective void date; as-of aging counts the release before it.
  • retainage_releases[].void_entry_id
    integer | null
  • retainage_releases[].void_reason
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)
  • 422Validation failed or the ledger refused the change

Example request

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

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • page
    integerquery
  • per_page
    integerquery
  • status
    stringquery
  • source
    stringquery
  • search
    stringquery
  • vendor_id
    integerquery
  • assigned_to_id
    integerquery
  • unassigned
    booleanquery

Response · 200 · object[]

  • id
    integerrequired
  • number
    stringrequired
  • source
    stringrequired
    One of: upload, email, portal.
  • status
    stringrequired
    One of: new, in_progress, drafted, rejected.
  • kind
    string
    One of: invoice, pay_app.
  • sender_email
    string | null
  • sender_name
    string | null
  • subject
    string | null
  • received_at
    string (date-time)required
  • file
    objectrequired
  • file.name
    stringrequired
  • file.content_type
    stringrequired
  • file.size_bytes
    integerrequired
  • file.sha256
    stringrequired
  • file.scan_status
    stringrequired
    One of: clean, internal_upload, unscanned_local, infected.
  • file.download_url
    string | null
  • vendor
    object | null
  • vendor.id
    integer
  • vendor.name
    string | null
  • suggested_vendor
    object | null
  • suggested_vendor.id
    integer
  • suggested_vendor.name
    string | null
  • invoice_number
    string | null
  • invoice_date
    string | null (date)
  • amount
    string | null
  • notes
    string | null
  • duplicates
    object[]required
  • duplicates[].kind
    stringrequired
    One of: file_hash, vendor_invoice.
  • duplicates[].captured_document_id
    integer
  • duplicates[].bill_id
    integer
  • duplicates[].number
    stringrequired
  • assigned_to
    object | null
  • assigned_to.id
    integer
  • assigned_to.name
    string | null
  • portal_grant_id
    integer | null
  • bill
    object | null
  • bill.id
    integer
  • bill.number
    string | null
  • bill.status
    string | null
  • reject_reason
    string | null
  • drafted_at
    string | null (date-time)
  • rejected_at
    string | null (date-time)
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 422Validation failed

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • file
    string (binary)required
  • kind
    string
    One of: invoice, pay_app.
  • notes
    string

Response · 201 · object

  • id
    integerrequired
  • number
    stringrequired
  • source
    stringrequired
    One of: upload, email, portal.
  • status
    stringrequired
    One of: new, in_progress, drafted, rejected.
  • kind
    string
    One of: invoice, pay_app.
  • sender_email
    string | null
  • sender_name
    string | null
  • subject
    string | null
  • received_at
    string (date-time)required
  • file
    objectrequired
  • file.name
    stringrequired
  • file.content_type
    stringrequired
  • file.size_bytes
    integerrequired
  • file.sha256
    stringrequired
  • file.scan_status
    stringrequired
    One of: clean, internal_upload, unscanned_local, infected.
  • file.download_url
    string | null
  • vendor
    object | null
  • vendor.id
    integer
  • vendor.name
    string | null
  • suggested_vendor
    object | null
  • suggested_vendor.id
    integer
  • suggested_vendor.name
    string | null
  • invoice_number
    string | null
  • invoice_date
    string | null (date)
  • amount
    string | null
  • notes
    string | null
  • duplicates
    object[]required
  • duplicates[].kind
    stringrequired
    One of: file_hash, vendor_invoice.
  • duplicates[].captured_document_id
    integer
  • duplicates[].bill_id
    integer
  • duplicates[].number
    stringrequired
  • assigned_to
    object | null
  • assigned_to.id
    integer
  • assigned_to.name
    string | null
  • portal_grant_id
    integer | null
  • bill
    object | null
  • bill.id
    integer
  • bill.number
    string | null
  • bill.status
    string | null
  • reject_reason
    string | null
  • drafted_at
    string | null (date-time)
  • rejected_at
    string | null (date-time)
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

Errors

  • 400Malformed body or Idempotency-Key
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 409Conflict (state guard)
  • 413File too large
  • 422Validation failed

Example request

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • source
    stringrequired
    One of: upload, email, portal.
  • status
    stringrequired
    One of: new, in_progress, drafted, rejected.
  • kind
    string
    One of: invoice, pay_app.
  • sender_email
    string | null
  • sender_name
    string | null
  • subject
    string | null
  • received_at
    string (date-time)required
  • file
    objectrequired
  • file.name
    stringrequired
  • file.content_type
    stringrequired
  • file.size_bytes
    integerrequired
  • file.sha256
    stringrequired
  • file.scan_status
    stringrequired
    One of: clean, internal_upload, unscanned_local, infected.
  • file.download_url
    string | null
  • vendor
    object | null
  • vendor.id
    integer
  • vendor.name
    string | null
  • suggested_vendor
    object | null
  • suggested_vendor.id
    integer
  • suggested_vendor.name
    string | null
  • invoice_number
    string | null
  • invoice_date
    string | null (date)
  • amount
    string | null
  • notes
    string | null
  • duplicates
    object[]required
  • duplicates[].kind
    stringrequired
    One of: file_hash, vendor_invoice.
  • duplicates[].captured_document_id
    integer
  • duplicates[].bill_id
    integer
  • duplicates[].number
    stringrequired
  • assigned_to
    object | null
  • assigned_to.id
    integer
  • assigned_to.name
    string | null
  • portal_grant_id
    integer | null
  • bill
    object | null
  • bill.id
    integer
  • bill.number
    string | null
  • bill.status
    string | null
  • reject_reason
    string | null
  • drafted_at
    string | null (date-time)
  • rejected_at
    string | null (date-time)
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

v1.0Implemented

Parameters

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

Request body

  • captured_document
    objectrequired
  • captured_document.vendor_id
    integer | null
  • captured_document.kind
    string
    One of: invoice, pay_app.
  • captured_document.invoice_number
    string | null
  • captured_document.invoice_date
    string | null (date)
  • captured_document.amount
    string | null
  • captured_document.notes
    string | null
  • captured_document.assigned_to_id
    integer | null
  • captured_document.status
    string
    One of: new, in_progress.

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • source
    stringrequired
    One of: upload, email, portal.
  • status
    stringrequired
    One of: new, in_progress, drafted, rejected.
  • kind
    string
    One of: invoice, pay_app.
  • sender_email
    string | null
  • sender_name
    string | null
  • subject
    string | null
  • received_at
    string (date-time)required
  • file
    objectrequired
  • file.name
    stringrequired
  • file.content_type
    stringrequired
  • file.size_bytes
    integerrequired
  • file.sha256
    stringrequired
  • file.scan_status
    stringrequired
    One of: clean, internal_upload, unscanned_local, infected.
  • file.download_url
    string | null
  • vendor
    object | null
  • vendor.id
    integer
  • vendor.name
    string | null
  • suggested_vendor
    object | null
  • suggested_vendor.id
    integer
  • suggested_vendor.name
    string | null
  • invoice_number
    string | null
  • invoice_date
    string | null (date)
  • amount
    string | null
  • notes
    string | null
  • duplicates
    object[]required
  • duplicates[].kind
    stringrequired
    One of: file_hash, vendor_invoice.
  • duplicates[].captured_document_id
    integer
  • duplicates[].bill_id
    integer
  • duplicates[].number
    stringrequired
  • assigned_to
    object | null
  • assigned_to.id
    integer
  • assigned_to.name
    string | null
  • portal_grant_id
    integer | null
  • bill
    object | null
  • bill.id
    integer
  • bill.number
    string | null
  • bill.status
    string | null
  • reject_reason
    string | null
  • drafted_at
    string | null (date-time)
  • rejected_at
    string | null (date-time)
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (state guard)
  • 422Validation failed

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • bill
    objectrequired
  • bill.kind
    string
  • bill.vendor_id
    integer
  • bill.entity_id
    integer | null
  • bill.invoice_number
    string | null
  • bill.invoice_date
    string (date)
  • bill.posting_date
    string (date)
  • bill.due_date
    string (date)
  • bill.term_id
    integer | null
  • bill.memo
    string | null
  • bill.retainage_percent
    string | null
  • bill.tax_code_id
    integer | null
  • bill.commitment_type
    string | null
  • bill.commitment_id
    integer | null
  • bill.pay_when_paid_pay_app_id
    integer | null
  • bill.pay_when_paid_mode
    string | null
  • bill.off_rent_date
    string | null (date)
  • bill.billed_through
    string | null (date)
  • bill.duplicate_override_reason
    string | null
  • bill.lines
    object[]required
  • bill.lines[].account_id
    integerrequired
  • bill.lines[].amount
    stringrequired
  • bill.lines[].description
    string | null
  • bill.lines[].retainage_percent
    string | null
  • bill.lines[].retainage_amount
    string | null
    Explicit retainage (at most the line amount); overrides retainage_percent.
  • bill.lines[].project_id
    integer | null
  • bill.lines[].cost_code_id
    integer | null
  • bill.lines[].cost_type_id
    integer | null
  • bill.lines[].equipment_id
    integer | null
  • bill.lines[].commitment_line_item_id
    integer | null
  • bill.lines[].quantity
    string | null
  • bill.lines[].unit_price
    string | null
  • bill.lines[].use_tax
    boolean
    Omitted 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_1099
    boolean
  • bill.lines[].tax_category
    string | null
    One of: material, fixture, labor, equipment, null.

Response · 201 · object

  • captured_document
    objectrequired
  • captured_document.id
    integerrequired
  • captured_document.number
    stringrequired
  • captured_document.source
    stringrequired
    One of: upload, email, portal.
  • captured_document.status
    stringrequired
    One of: new, in_progress, drafted, rejected.
  • captured_document.kind
    string
    One of: invoice, pay_app.
  • captured_document.sender_email
    string | null
  • captured_document.sender_name
    string | null
  • captured_document.subject
    string | null
  • captured_document.received_at
    string (date-time)required
  • captured_document.file
    objectrequired
  • captured_document.vendor
    object | null
  • captured_document.suggested_vendor
    object | null
  • captured_document.invoice_number
    string | null
  • captured_document.invoice_date
    string | null (date)
  • captured_document.amount
    string | null
  • captured_document.notes
    string | null
  • captured_document.duplicates
    object[]required
  • captured_document.assigned_to
    object | null
  • captured_document.portal_grant_id
    integer | null
  • captured_document.bill
    object | null
  • captured_document.reject_reason
    string | null
  • captured_document.drafted_at
    string | null (date-time)
  • captured_document.rejected_at
    string | null (date-time)
  • captured_document.created_at
    string (date-time)
  • captured_document.updated_at
    string (date-time)
  • bill
    objectrequired
  • bill.id
    integer
  • bill.number
    string
  • bill.status
    string
  • bill.total
    string
  • bill.links
    object

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (state guard)
  • 422Validation failed

Example request

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

Download a captured file

Always sent as an attachment (application/octet-stream), never rendered inline. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · string (binary)

No documented fields.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

Reject a captured document

Needs ap_enter and a reason (3-500 characters). Final; audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • reject
    objectrequired
  • reject.reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • source
    stringrequired
    One of: upload, email, portal.
  • status
    stringrequired
    One of: new, in_progress, drafted, rejected.
  • kind
    string
    One of: invoice, pay_app.
  • sender_email
    string | null
  • sender_name
    string | null
  • subject
    string | null
  • received_at
    string (date-time)required
  • file
    objectrequired
  • file.name
    stringrequired
  • file.content_type
    stringrequired
  • file.size_bytes
    integerrequired
  • file.sha256
    stringrequired
  • file.scan_status
    stringrequired
    One of: clean, internal_upload, unscanned_local, infected.
  • file.download_url
    string | null
  • vendor
    object | null
  • vendor.id
    integer
  • vendor.name
    string | null
  • suggested_vendor
    object | null
  • suggested_vendor.id
    integer
  • suggested_vendor.name
    string | null
  • invoice_number
    string | null
  • invoice_date
    string | null (date)
  • amount
    string | null
  • notes
    string | null
  • duplicates
    object[]required
  • duplicates[].kind
    stringrequired
    One of: file_hash, vendor_invoice.
  • duplicates[].captured_document_id
    integer
  • duplicates[].bill_id
    integer
  • duplicates[].number
    stringrequired
  • assigned_to
    object | null
  • assigned_to.id
    integer
  • assigned_to.name
    string | null
  • portal_grant_id
    integer | null
  • bill
    object | null
  • bill.id
    integer
  • bill.number
    string | null
  • bill.status
    string | null
  • reject_reason
    string | null
  • drafted_at
    string | null (date-time)
  • rejected_at
    string | null (date-time)
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (state guard)
  • 422Validation failed

Example request

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

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • vendor_id
    integer | null
  • vendor_rule
    string | null
    One of: keyed, portal_grant, sender, null.
  • coding
    object[]required
  • coding[].account_id
    integerrequired
  • coding[].cost_code_id
    integer | null
  • coding[].cost_type_id
    integer | null
  • coding[].project_id
    integer | null
  • coding[].uses
    integerrequired
  • coding[].last_used
    string
  • coding[].rule
    stringrequired
    One of: vendor_history, vendor_default_account.
  • open_commitment_lines
    object[]required
  • open_commitment_lines[].commitment_type
    string
  • open_commitment_lines[].commitment_id
    integer
  • open_commitment_lines[].commitment_number
    string
  • open_commitment_lines[].project_id
    integer
  • open_commitment_lines[].commitment_line_item_id
    integer
  • open_commitment_lines[].cost_code_id
    integer
  • open_commitment_lines[].description
    string | null
  • open_commitment_lines[].amount
    string
  • open_commitment_lines[].billed
    string
  • open_commitment_lines[].remaining
    string
  • open_commitment_lines[].unit_cost
    string | null
  • profile
    object | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • reprint
    objectrequired
  • reprint.reason
    stringrequired

Response · 201 · object

  • id
    integerrequired
  • check_number
    stringrequired
  • ap_payment_id
    integerrequired
  • amount
    stringrequired
  • status
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed or the ledger refused the change

Example request

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

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

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • kind
    stringrequired
    One of: coi, w9, license, prequalification, stop_pay.
  • vendor_id
    integer | nullrequired
  • commitment_type
    string | nullrequired
    One of: WorkOrderContract, PurchaseOrderContract, null.
  • commitment_id
    integer | nullrequired
  • notes
    string | nullrequired
  • created_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/compliance_requirements" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Payable

POST /rest/v1.0/companies/{company_id}/accounting/ap/compliance_requirements

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

v1.0Implemented

Parameters

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

Request body

  • compliance_requirement
    objectrequired
  • compliance_requirement.kind
    stringrequired
    One of: coi, w9, license, prequalification, stop_pay.
  • compliance_requirement.vendor_id
    integer | null
  • compliance_requirement.commitment_type
    string | null
    One of: WorkOrderContract, PurchaseOrderContract, null.
  • compliance_requirement.commitment_id
    integer | null
  • compliance_requirement.notes
    string | null

Response · 201 · object

  • id
    integerrequired
  • kind
    stringrequired
    One of: coi, w9, license, prequalification, stop_pay.
  • vendor_id
    integer | nullrequired
  • commitment_type
    string | nullrequired
    One of: WorkOrderContract, PurchaseOrderContract, null.
  • commitment_id
    integer | nullrequired
  • notes
    string | nullrequired
  • created_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed or the ledger refused the change

Example request

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

v1.0Implemented

Parameters

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

Response · 204

No response body.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • year
    integerquery
  • entity_id
    integerquery
    Only this payer entity. Each entity is its own payer: forms are per (entity, vendor) with the threshold per payer.

Response · 200 · object

  • year
    integerrequired
  • forms
    object[]required
  • forms[].entity_id
    integerrequired
  • forms[].entity_code
    string | nullrequired
  • forms[].vendor_id
    integerrequired
  • forms[].vendor_name
    string | nullrequired
  • forms[].form
    stringrequired
    One of: NEC, MISC.
  • forms[].boxes
    objectrequired
  • forms[].required
    booleanrequired
  • forms[].reasons
    string[]required
  • forms[].filing_status
    string
    Against the latest IRIS or Pub 1220 export: changed means the live amounts differ from what was filed. One of: not_filed, filed, changed.
  • forms[].filed
    object | null
  • explain
    objectrequired
  • explain.steps
    object[]required
  • summary_1096
    object[]required
    Form 1096-style totals per payer entity and form: required forms and the total reported.
  • summary_1096[].entity_id
    integerrequired
  • summary_1096[].entity_code
    string | nullrequired
  • summary_1096[].form
    stringrequired
    One of: NEC, MISC.
  • summary_1096[].forms
    integerrequired
  • summary_1096[].total
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/form_1099" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Payable

GET /rest/v1.0/companies/{company_id}/accounting/ap/form_1099/copy_b

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

v1.0Implemented

Parameters

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

Response · 200 · string (binary)

No documented fields.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access or missing manage_vendor_banking
  • 404No required 1099 for this vendor and payer
  • 422year, entity_id and vendor_id are required, or the payer entity lacks its tax identity

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • iris
    objectrequired
  • iris.year
    integerrequired
  • iris.form
    stringrequired
    One of: NEC, MISC.
  • iris.template
    stringrequired
    The CSV template downloaded from the IRIS Taxpayer Portal for this tax year and form (only its first line, the header row, is used)
  • iris.corrected
    boolean
    Refused: the portal CSV has no corrected-return column
  • iris.issuer
    object
    Overrides the entity tax identity (EIN, legal name, address, phone) for a one-entity export. Omitted, the issuer comes from the entity.
  • iris.issuer.tin
    stringrequired
  • iris.issuer.tin_type
    string
    One of: EIN, SSN.
  • iris.issuer.name
    stringrequired
  • iris.issuer.name2
    string
  • iris.issuer.address
    stringrequired
  • iris.issuer.address2
    string
  • iris.issuer.city
    stringrequired
  • iris.issuer.state
    stringrequired
  • iris.issuer.zip
    stringrequired
  • iris.issuer.phone
    string
  • iris.entity_id
    integer | null
    The payer entity; required when forms span several entities.

Response · 200 · object

  • year
    integerrequired
  • form
    stringrequired
    One of: NEC, MISC.
  • files
    object[]required
  • files[].filename
    stringrequired
  • files[].records
    integerrequired
    Returns in this file (header row excluded), at most 250
  • files[].csv
    stringrequired
    CSV text: the template header row, then one row per return, CRLF line endings
  • warnings
    string[]required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 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

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

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

v1.0Implemented

Parameters

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

Request body

  • pub1220
    objectrequired
  • pub1220.year
    integerrequired
  • pub1220.form
    stringrequired
    One of: NEC, MISC.
  • pub1220.test
    boolean
  • pub1220.transmitter
    objectrequired
  • pub1220.transmitter.tin
    stringrequired
  • pub1220.transmitter.tcc
    stringrequired
  • pub1220.transmitter.name
    stringrequired
  • pub1220.transmitter.company_name
    stringrequired
  • pub1220.transmitter.address
    stringrequired
  • pub1220.transmitter.city
    stringrequired
  • pub1220.transmitter.state
    stringrequired
  • pub1220.transmitter.zip
    stringrequired
  • pub1220.transmitter.contact_name
    stringrequired
  • pub1220.transmitter.contact_phone
    stringrequired
  • pub1220.transmitter.contact_email
    string (email)required
  • pub1220.issuer
    object
    Overrides the entity tax identity (EIN, legal name, address, phone) for a one-entity export. Omitted, the issuer comes from the entity.
  • pub1220.issuer.tin
    stringrequired
  • pub1220.issuer.name
    stringrequired
  • pub1220.issuer.address
    stringrequired
  • pub1220.issuer.city
    stringrequired
  • pub1220.issuer.state
    stringrequired
  • pub1220.issuer.zip
    stringrequired
  • pub1220.issuer.phone
    stringrequired
  • pub1220.entity_id
    integer | null
    Only this payer entity; omitted, one issuer (A) record per entity with forms.
  • pub1220.corrected
    boolean
    Only 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 token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed, no vendor needs this form, or the file failed Pub 1220 checks (FIRE is closed for payment years 2026 and later)

Example request

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

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • year
    integerquery
  • entity_id
    integerqueryrequired
  • lookback_liability
    stringquery

Response · 200 · object

  • year
    integerrequired
  • entity_id
    integerrequired
  • lines
    objectrequired
    Form 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.1
    string
  • lines.2
    string
  • lines.3
    string
  • lines.4
    string
  • lines.5
    string
  • lines.6
    string
  • line_7
    object | nullrequired
    Monthly summary, only for a monthly depositor for the whole year with line 3 of 2,500.00 or more.
  • line_7.months
    string[]
  • line_7.total
    string
  • form_945a_required
    booleanrequired
  • schedule
    stringrequired
    One of: monthly, semiweekly.
  • lookback_liability
    stringrequired
  • may_pay_with_return
    booleanrequired
  • liability_by_date
    object[]required
  • liability_by_date[].date
    string (date)
  • liability_by_date[].amount
    string
  • deposits
    object[]required
  • deposits[].due_date
    string (date)
  • deposits[].amount
    string
  • deposits[].rule
    string
    One of: monthly, semiweekly, next_day.
  • deposits[].liability_dates
    string (date)[]
  • ledger_withheld
    stringrequired
  • warnings
    string[]required
  • explain
    objectrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 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

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

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

v1.0Implemented

Parameters

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

Request body

  • form_945
    objectrequired
  • form_945.year
    integerrequired
  • form_945.entity_id
    integerrequired
  • form_945.lookback_liability
    string | null

Response · 200 · object

  • year
    integerrequired
  • entity_id
    integerrequired
  • deposits
    object[]required
  • deposits[].tax_form
    string
  • deposits[].tax_type_code
    string
  • deposits[].tax_period_end
    string (date)
  • deposits[].settlement_date
    string (date)
  • deposits[].amount
    string
  • deposits[].txp
    string

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 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

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

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • page
    integerquery
  • per_page
    integerquery
  • status
    stringquery
    open, resolved, overridden (comma-separated)
  • type
    stringquery
    qty_over, price_over, no_receipt, no_po, over_commitment (comma-separated)
  • vendor_id
    integerquery
  • project_id
    integerquery
  • entity_id
    integerquery
  • bill_id
    integerquery
  • min_age
    integerquery
    Days since detection, at least
  • max_age
    integerquery
    Days since detection, at most

Response · 200 · object[]

  • id
    integerrequired
  • bill_id
    integerrequired
  • bill_number
    string | nullrequired
  • invoice_number
    string | nullrequired
  • bill_status
    string | nullrequired
  • bill_revision
    integerrequired
  • line_no
    integer | nullrequired
    Bill line; null for the whole bill (over_commitment).
  • type
    stringrequired
    One of: qty_over, price_over, no_receipt, no_po, over_commitment.
  • status
    stringrequired
    One of: open, resolved, overridden.
  • entity_id
    integerrequired
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • project_id
    integer | nullrequired
  • project_name
    string | nullrequired
  • commitment_type
    string | nullrequired
  • commitment_id
    integer | nullrequired
  • commitment_line_item_id
    integer | nullrequired
  • cost_type_id
    integer | nullrequired
  • amount
    stringrequired
    Money at stake: |price variance|, the excess quantity at the bill price, the unreceived or unordered line amount, or the over-commitment.
  • message
    stringrequired
  • details
    objectrequired
    Figures behind the exception as of the last evaluation (quantities, prices, tolerance applied).
  • detected_at
    string (date-time)required
  • last_evaluated_at
    string (date-time)required
  • age_days
    integer | nullrequired
  • age_bucket
    string | nullrequired
    One of: 0_7, 8_14, 15_30, 31_plus, null.
  • resolution
    string | nullrequired
    receipt, re_evaluated, bill_corrected, bill_returned or override.
  • resolved_at
    string | null (date-time)required
  • resolved_by_id
    integer | nullrequired
  • override_reason
    string | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed

Example request

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • bill_id
    integerrequired
  • bill_number
    string | nullrequired
  • invoice_number
    string | nullrequired
  • bill_status
    string | nullrequired
  • bill_revision
    integerrequired
  • line_no
    integer | nullrequired
    Bill line; null for the whole bill (over_commitment).
  • type
    stringrequired
    One of: qty_over, price_over, no_receipt, no_po, over_commitment.
  • status
    stringrequired
    One of: open, resolved, overridden.
  • entity_id
    integerrequired
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • project_id
    integer | nullrequired
  • project_name
    string | nullrequired
  • commitment_type
    string | nullrequired
  • commitment_id
    integer | nullrequired
  • commitment_line_item_id
    integer | nullrequired
  • cost_type_id
    integer | nullrequired
  • amount
    stringrequired
    Money at stake: |price variance|, the excess quantity at the bill price, the unreceived or unordered line amount, or the over-commitment.
  • message
    stringrequired
  • details
    objectrequired
    Figures behind the exception as of the last evaluation (quantities, prices, tolerance applied).
  • detected_at
    string (date-time)required
  • last_evaluated_at
    string (date-time)required
  • age_days
    integer | nullrequired
  • age_bucket
    string | nullrequired
    One of: 0_7, 8_14, 15_30, 31_plus, null.
  • resolution
    string | nullrequired
    receipt, re_evaluated, bill_corrected, bill_returned or override.
  • resolved_at
    string | null (date-time)required
  • resolved_by_id
    integer | nullrequired
  • override_reason
    string | nullrequired
  • can_override
    booleanrequired
    The exception is open and the caller is not a maker of the bill (ap_approve is still checked on override).
  • po
    object | nullrequired
  • po.commitment_type
    string | nullrequired
  • po.id
    integerrequired
  • po.number
    stringrequired
  • po.title
    string | nullrequired
  • po.line
    object | nullrequired
  • receipts
    object[]required
  • receipts[].receipt_id
    integerrequired
  • receipts[].number
    stringrequired
  • receipts[].receipt_date
    string (date)required
  • receipts[].quantity
    stringrequired
  • receipts[].amount
    stringrequired
    Money, 2 dp
  • receipts[].voided
    booleanrequired
  • other_bills
    object[]required
    Other posted or pending bill lines on the same PO line.
  • other_bills[].bill_id
    integerrequired
  • other_bills[].number
    stringrequired
  • other_bills[].status
    stringrequired
  • other_bills[].kind
    stringrequired
  • other_bills[].line_no
    integerrequired
  • other_bills[].quantity
    string | nullrequired
  • other_bills[].amount
    stringrequired
    Money, 2 dp
  • bill
    objectrequired
  • bill.id
    integerrequired
  • bill.number
    stringrequired
  • bill.invoice_number
    string | nullrequired
  • bill.status
    stringrequired
  • bill.revision
    integerrequired
  • bill.total
    stringrequired
    Money, 2 dp
  • bill.line
    object | nullrequired
  • other_exceptions
    object[]required
  • other_exceptions[].id
    integerrequired
  • other_exceptions[].line_no
    integer | nullrequired
  • other_exceptions[].type
    stringrequired
    One of: qty_over, price_over, no_receipt, no_po, over_commitment.
  • other_exceptions[].status
    stringrequired
    One of: open, resolved, overridden.
  • other_exceptions[].amount
    stringrequired
    Money, 2 dp
  • other_exceptions[].message
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • override
    objectrequired
  • override.reason
    stringrequired
  • override.all_on_bill
    boolean

Response · 200 · object

  • id
    integerrequired
  • bill_id
    integerrequired
  • bill_number
    string | nullrequired
  • invoice_number
    string | nullrequired
  • bill_status
    string | nullrequired
  • bill_revision
    integerrequired
  • line_no
    integer | nullrequired
    Bill line; null for the whole bill (over_commitment).
  • type
    stringrequired
    One of: qty_over, price_over, no_receipt, no_po, over_commitment.
  • status
    stringrequired
    One of: open, resolved, overridden.
  • entity_id
    integerrequired
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • project_id
    integer | nullrequired
  • project_name
    string | nullrequired
  • commitment_type
    string | nullrequired
  • commitment_id
    integer | nullrequired
  • commitment_line_item_id
    integer | nullrequired
  • cost_type_id
    integer | nullrequired
  • amount
    stringrequired
    Money at stake: |price variance|, the excess quantity at the bill price, the unreceived or unordered line amount, or the over-commitment.
  • message
    stringrequired
  • details
    objectrequired
    Figures behind the exception as of the last evaluation (quantities, prices, tolerance applied).
  • detected_at
    string (date-time)required
  • last_evaluated_at
    string (date-time)required
  • age_days
    integer | nullrequired
  • age_bucket
    string | nullrequired
    One of: 0_7, 8_14, 15_30, 31_plus, null.
  • resolution
    string | nullrequired
    receipt, re_evaluated, bill_corrected, bill_returned or override.
  • resolved_at
    string | null (date-time)required
  • resolved_by_id
    integer | nullrequired
  • override_reason
    string | nullrequired
  • can_override
    booleanrequired
    The exception is open and the caller is not a maker of the bill (ap_approve is still checked on override).
  • po
    object | nullrequired
  • po.commitment_type
    string | nullrequired
  • po.id
    integerrequired
  • po.number
    stringrequired
  • po.title
    string | nullrequired
  • po.line
    object | nullrequired
  • receipts
    object[]required
  • receipts[].receipt_id
    integerrequired
  • receipts[].number
    stringrequired
  • receipts[].receipt_date
    string (date)required
  • receipts[].quantity
    stringrequired
  • receipts[].amount
    stringrequired
    Money, 2 dp
  • receipts[].voided
    booleanrequired
  • other_bills
    object[]required
    Other posted or pending bill lines on the same PO line.
  • other_bills[].bill_id
    integerrequired
  • other_bills[].number
    stringrequired
  • other_bills[].status
    stringrequired
  • other_bills[].kind
    stringrequired
  • other_bills[].line_no
    integerrequired
  • other_bills[].quantity
    string | nullrequired
  • other_bills[].amount
    stringrequired
    Money, 2 dp
  • bill
    objectrequired
  • bill.id
    integerrequired
  • bill.number
    stringrequired
  • bill.invoice_number
    string | nullrequired
  • bill.status
    stringrequired
  • bill.revision
    integerrequired
  • bill.total
    stringrequired
    Money, 2 dp
  • bill.line
    object | nullrequired
  • other_exceptions
    object[]required
  • other_exceptions[].id
    integerrequired
  • other_exceptions[].line_no
    integer | nullrequired
  • other_exceptions[].type
    stringrequired
    One of: qty_over, price_over, no_receipt, no_po, over_commitment.
  • other_exceptions[].status
    stringrequired
    One of: open, resolved, overridden.
  • other_exceptions[].amount
    stringrequired
    Money, 2 dp
  • other_exceptions[].message
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict
  • 422Validation failed

Example request

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

List payment runs

Paginated. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • number
    stringrequired
  • status
    stringrequired
    One of: draft, posted.
  • pay_date
    string (date)required
  • cash_account_id
    integerrequired
  • memo
    string | nullrequired
  • prepared_by_id
    integerrequired
  • released_by_id
    integer | nullrequired
  • released_at
    string | null (date-time)required
  • ach_generated_at
    string | null (date-time)required
    When the NACHA file was last generated (null: never).
  • ach_file_id_modifier
    string | nullrequired
    File id modifier of the last NACHA file: A, then B, C… on each audited re-send.
  • total
    stringrequired
    Money, 2 dp
  • payment_count
    integerrequired
  • payments
    object[]required
  • payments[].id
    integerrequired
  • payments[].run_id
    integer | nullrequired
  • payments[].vendor_id
    integerrequired
  • payments[].vendor_name
    string | nullrequired
  • payments[].entity_id
    integerrequired
  • payments[].method
    stringrequired
    One of: check, ach, wire, virtual_card, owner_direct.
  • payments[].check_number
    string | nullrequired
  • payments[].payment_date
    string (date)required
  • payments[].cash_account_id
    integerrequired
  • payments[].amount
    stringrequired
    Money, 2 dp
  • payments[].discount_amount
    stringrequired
    Money, 2 dp
  • payments[].withholding_amount
    stringrequired
    Money, 2 dp
  • payments[].joint_payees
    object[]required
  • payments[].customer_id
    integer | nullrequired
  • payments[].status
    stringrequired
    One of: draft, posted, void.
  • payments[].memo
    string | nullrequired
  • payments[].entry_id
    integer | nullrequired
  • payments[].voided_at
    string | null (date-time)required
  • payments[].void_entry_id
    integer | nullrequired
  • payments[].void_reason
    string | nullrequired
  • payments[].ach_trace_number
    string | nullrequired
    ACH: trace number in the last generated NACHA file.
  • payments[].applications
    object[]required
  • payments[].created_at
    string (date-time)required
  • created_at
    string (date-time)required
  • ach_resend_requested_by_id
    integer | null
    Pending requester; null when there is no pending resend.
  • ach_resend_reason
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payment_runs" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Payable

POST /rest/v1.0/companies/{company_id}/accounting/ap/payment_runs

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

v1.0Implemented

Parameters

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

Request body

  • payment_run
    objectrequired
  • payment_run.pay_date
    string (date)required
  • payment_run.cash_account_id
    integer | null
  • payment_run.due_by
    string (date)
  • payment_run.vendor_ids
    integer[]
  • payment_run.memo
    string | null
  • payment_run.payments
    object[]
  • payment_run.payments[].vendor_id
    integerrequired
  • payment_run.payments[].method
    string
  • payment_run.payments[].customer_id
    integer | null
  • payment_run.payments[].joint_payees
    object[]
  • payment_run.payments[].joint_payees[].name
    stringrequired
  • payment_run.payments[].joint_payees[].amount
    stringrequired
  • payment_run.payments[].bills
    object[]required
  • payment_run.payments[].bills[].bill_id
    integerrequired
  • payment_run.payments[].bills[].amount
    string

Response · 201 · object

  • id
    integerrequired
  • number
    stringrequired
  • status
    stringrequired
    One of: draft, posted.
  • pay_date
    string (date)required
  • cash_account_id
    integerrequired
  • memo
    string | nullrequired
  • prepared_by_id
    integerrequired
  • released_by_id
    integer | nullrequired
  • released_at
    string | null (date-time)required
  • total
    stringrequired
    Money, 2 dp
  • payment_count
    integerrequired
  • payments
    object[]required
  • payments[].id
    integerrequired
  • payments[].run_id
    integer | nullrequired
  • payments[].vendor_id
    integerrequired
  • payments[].vendor_name
    string | nullrequired
  • payments[].entity_id
    integerrequired
  • payments[].method
    stringrequired
    One of: check, ach, wire, virtual_card, owner_direct.
  • payments[].check_number
    string | nullrequired
  • payments[].payment_date
    string (date)required
  • payments[].cash_account_id
    integerrequired
  • payments[].amount
    stringrequired
    Money, 2 dp
  • payments[].discount_amount
    stringrequired
    Money, 2 dp
  • payments[].withholding_amount
    stringrequired
    Money, 2 dp
  • payments[].joint_payees
    object[]required
  • payments[].customer_id
    integer | nullrequired
  • payments[].status
    stringrequired
    One of: draft, posted, void.
  • payments[].memo
    string | nullrequired
  • payments[].entry_id
    integer | nullrequired
  • payments[].voided_at
    string | null (date-time)required
  • payments[].void_entry_id
    integer | nullrequired
  • payments[].void_reason
    string | nullrequired
  • payments[].ach_trace_number
    string | nullrequired
    ACH: trace number in the last generated NACHA file.
  • payments[].applications
    object[]required
  • payments[].created_at
    string (date-time)required
  • created_at
    string (date-time)required
  • held
    object[]required
  • held[].bill_id
    integerrequired
  • held[].number
    stringrequired
  • held[].vendor_id
    integerrequired
  • held[].holds
    object[]required

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)
  • 422Validation failed or the ledger refused the change

Example request

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • status
    stringrequired
    One of: draft, posted.
  • pay_date
    string (date)required
  • cash_account_id
    integerrequired
  • memo
    string | nullrequired
  • prepared_by_id
    integerrequired
  • released_by_id
    integer | nullrequired
  • released_at
    string | null (date-time)required
  • ach_generated_at
    string | null (date-time)required
    When the NACHA file was last generated (null: never).
  • ach_file_id_modifier
    string | nullrequired
    File id modifier of the last NACHA file: A, then B, C… on each audited re-send.
  • total
    stringrequired
    Money, 2 dp
  • payment_count
    integerrequired
  • payments
    object[]required
  • payments[].id
    integerrequired
  • payments[].run_id
    integer | nullrequired
  • payments[].vendor_id
    integerrequired
  • payments[].vendor_name
    string | nullrequired
  • payments[].entity_id
    integerrequired
  • payments[].method
    stringrequired
    One of: check, ach, wire, virtual_card, owner_direct.
  • payments[].check_number
    string | nullrequired
  • payments[].payment_date
    string (date)required
  • payments[].cash_account_id
    integerrequired
  • payments[].amount
    stringrequired
    Money, 2 dp
  • payments[].discount_amount
    stringrequired
    Money, 2 dp
  • payments[].withholding_amount
    stringrequired
    Money, 2 dp
  • payments[].joint_payees
    object[]required
  • payments[].customer_id
    integer | nullrequired
  • payments[].status
    stringrequired
    One of: draft, posted, void.
  • payments[].memo
    string | nullrequired
  • payments[].entry_id
    integer | nullrequired
  • payments[].voided_at
    string | null (date-time)required
  • payments[].void_entry_id
    integer | nullrequired
  • payments[].void_reason
    string | nullrequired
  • payments[].ach_trace_number
    string | nullrequired
    ACH: trace number in the last generated NACHA file.
  • payments[].applications
    object[]required
  • payments[].created_at
    string (date-time)required
  • created_at
    string (date-time)required
  • ach_resend_requested_by_id
    integer | null
    Pending requester; null when there is no pending resend.
  • ach_resend_reason
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

v1.0Implemented

Parameters

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

Response · 204

No response body.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed or the ledger refused the change

Example request

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

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • id
    integerpathrequired
  • format
    stringquery
    pdf 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_id
    integerrequired
  • check_number
    stringrequired
  • date
    string (date)required
  • amount
    stringrequired
  • amount_words
    stringrequired
  • payee_line
    stringrequired
  • memo
    string | nullrequired
  • micr
    stringrequired
  • stub
    object[]required
  • stub[].reference
    stringrequired
  • stub[].gross
    stringrequired
  • stub[].discount
    stringrequired
  • stub[].net
    stringrequired
  • stub[].date
    string

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 409A released check is not in the check register (check_not_registered)
  • 422Validation failed or the ledger refused the change

Example request

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

ACH (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.

v1.0Implemented

Parameters

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

Response · 200 · string

No documented fields.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Already generated (ach_already_generated)
  • 422Validation failed or the ledger refused the change

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • resend
    objectrequired
  • resend.reason
    stringrequired
  • resend.action
    stringrequired
    Explicit workflow intent; requesting cannot confirm an existing request. One of: request, confirm.
  • resend.previous_file_id_modifier
    stringrequired
    Current 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 token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Another generation ran at the same time
  • 422Validation failed or the ledger refused the change

Example request

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

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

v1.0Implemented

Parameters

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

Response · 200 · string

No documented fields.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed or the ledger refused the change

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • reject
    objectrequired
  • reject.reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • status
    stringrequired
    One of: draft, posted.
  • pay_date
    string (date)required
  • cash_account_id
    integerrequired
  • memo
    string | nullrequired
  • prepared_by_id
    integerrequired
  • released_by_id
    integer | nullrequired
  • released_at
    string | null (date-time)required
  • ach_generated_at
    string | null (date-time)required
    When the NACHA file was last generated (null: never).
  • ach_file_id_modifier
    string | nullrequired
    File id modifier of the last NACHA file: A, then B, C… on each audited re-send.
  • total
    stringrequired
    Money, 2 dp
  • payment_count
    integerrequired
  • payments
    object[]required
  • payments[].id
    integerrequired
  • payments[].run_id
    integer | nullrequired
  • payments[].vendor_id
    integerrequired
  • payments[].vendor_name
    string | nullrequired
  • payments[].entity_id
    integerrequired
  • payments[].method
    stringrequired
    One of: check, ach, wire, virtual_card, owner_direct.
  • payments[].check_number
    string | nullrequired
  • payments[].payment_date
    string (date)required
  • payments[].cash_account_id
    integerrequired
  • payments[].amount
    stringrequired
    Money, 2 dp
  • payments[].discount_amount
    stringrequired
    Money, 2 dp
  • payments[].withholding_amount
    stringrequired
    Money, 2 dp
  • payments[].joint_payees
    object[]required
  • payments[].customer_id
    integer | nullrequired
  • payments[].status
    stringrequired
    One of: draft, posted, void.
  • payments[].memo
    string | nullrequired
  • payments[].entry_id
    integer | nullrequired
  • payments[].voided_at
    string | null (date-time)required
  • payments[].void_entry_id
    integer | nullrequired
  • payments[].void_reason
    string | nullrequired
  • payments[].ach_trace_number
    string | nullrequired
    ACH: trace number in the last generated NACHA file.
  • payments[].applications
    object[]required
  • payments[].created_at
    string (date-time)required
  • created_at
    string (date-time)required
  • ach_resend_requested_by_id
    integer | null
    Pending requester; null when there is no pending resend.
  • ach_resend_reason
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, or wrong company
  • 404Not found in this company
  • 422Validation failed

Example request

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

Release (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.

v1.0Implemented

Parameters

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

Request body

  • approve
    object
  • approve.reason
    string
    Required 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

  • id
    integerrequired
  • number
    stringrequired
  • status
    stringrequired
    One of: draft, posted.
  • pay_date
    string (date)required
  • cash_account_id
    integerrequired
  • memo
    string | nullrequired
  • prepared_by_id
    integerrequired
  • released_by_id
    integer | nullrequired
  • released_at
    string | null (date-time)required
  • ach_generated_at
    string | null (date-time)required
    When the NACHA file was last generated (null: never).
  • ach_file_id_modifier
    string | nullrequired
    File id modifier of the last NACHA file: A, then B, C… on each audited re-send.
  • total
    stringrequired
    Money, 2 dp
  • payment_count
    integerrequired
  • payments
    object[]required
  • payments[].id
    integerrequired
  • payments[].run_id
    integer | nullrequired
  • payments[].vendor_id
    integerrequired
  • payments[].vendor_name
    string | nullrequired
  • payments[].entity_id
    integerrequired
  • payments[].method
    stringrequired
    One of: check, ach, wire, virtual_card, owner_direct.
  • payments[].check_number
    string | nullrequired
  • payments[].payment_date
    string (date)required
  • payments[].cash_account_id
    integerrequired
  • payments[].amount
    stringrequired
    Money, 2 dp
  • payments[].discount_amount
    stringrequired
    Money, 2 dp
  • payments[].withholding_amount
    stringrequired
    Money, 2 dp
  • payments[].joint_payees
    object[]required
  • payments[].customer_id
    integer | nullrequired
  • payments[].status
    stringrequired
    One of: draft, posted, void.
  • payments[].memo
    string | nullrequired
  • payments[].entry_id
    integer | nullrequired
  • payments[].voided_at
    string | null (date-time)required
  • payments[].void_entry_id
    integer | nullrequired
  • payments[].void_reason
    string | nullrequired
  • payments[].ach_trace_number
    string | nullrequired
    ACH: trace number in the last generated NACHA file.
  • payments[].applications
    object[]required
  • payments[].created_at
    string (date-time)required
  • created_at
    string (date-time)required
  • ach_resend_requested_by_id
    integer | null
    Pending requester; null when there is no pending resend.
  • ach_resend_reason
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)
  • 422Validation failed or the ledger refused the change

Example request

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

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • pay_date
    string (date)query
  • due_by
    string (date)query

Response · 200 · object[]

  • bill_id
    integerrequired
  • number
    stringrequired
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • invoice_number
    string | nullrequired
  • due_date
    string (date)required
  • open_amount
    stringrequired
    Money, 2 dp
  • payable_amount
    stringrequired
    Money, 2 dp
  • discount
    stringrequired
    Money, 2 dp
  • holds
    object[]required
  • holds[].code
    stringrequired
    Hold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
  • holds[].message
    stringrequired
  • holds[].overridden
    booleanrequired
  • payable
    booleanrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payment_selection" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Payable

GET /rest/v1.0/companies/{company_id}/accounting/ap/payments

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • page
    integerquery
  • per_page
    integerquery
  • vendor_id
    integerquery
  • filters[status]
    stringquery
  • updated_since
    string (date-time)query
    Delta 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.
  • cursor
    stringquery
    Opaque keyset cursor from a previous response's Next-Cursor header; each page costs the same however deep it is.

Response · 200 · object[]

  • id
    integerrequired
  • run_id
    integer | nullrequired
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • entity_id
    integerrequired
  • method
    stringrequired
    One of: check, ach, wire, virtual_card, owner_direct.
  • check_number
    string | nullrequired
  • payment_date
    string (date)required
  • cash_account_id
    integerrequired
  • amount
    stringrequired
    Money, 2 dp
  • discount_amount
    stringrequired
    Money, 2 dp
  • withholding_amount
    stringrequired
    Money, 2 dp
  • joint_payees
    object[]required
  • joint_payees[].name
    stringrequired
  • joint_payees[].amount
    stringrequired
  • customer_id
    integer | nullrequired
  • status
    stringrequired
    One of: draft, posted, void.
  • memo
    string | nullrequired
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • ach_trace_number
    string | nullrequired
    ACH: trace number in the last generated NACHA file.
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].bill_id
    integerrequired
  • applications[].payment_id
    integer | nullrequired
  • applications[].credit_id
    integer | nullrequired
  • applications[].date
    string (date)required
  • applications[].amount
    stringrequired
    Money, 2 dp
  • applications[].discount
    stringrequired
    Money, 2 dp
  • applications[].withholding
    stringrequired
    Money, 2 dp
  • applications[].voided
    booleanrequired
  • applications[].bill_number
    stringrequired
  • applications[].invoice_number
    string | nullrequired
  • created_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payments" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Payable

POST /rest/v1.0/companies/{company_id}/accounting/ap/payments

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

v1.0Implemented

Parameters

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

Request body

  • payment
    objectrequired
  • payment.pay_date
    string (date)required
  • payment.cash_account_id
    integer | null
  • payment.memo
    string | null
  • payment.vendor_id
    integerrequired
  • payment.method
    string
  • payment.customer_id
    integer | null
  • payment.joint_payees
    object[]
  • payment.joint_payees[].name
    stringrequired
  • payment.joint_payees[].amount
    stringrequired
  • payment.bills
    object[]required
  • payment.bills[].bill_id
    integerrequired
  • payment.bills[].amount
    string

Response · 201 · object

  • id
    integerrequired
  • number
    stringrequired
  • status
    stringrequired
    One of: draft, posted.
  • pay_date
    string (date)required
  • cash_account_id
    integerrequired
  • memo
    string | nullrequired
  • prepared_by_id
    integerrequired
  • released_by_id
    integer | nullrequired
  • released_at
    string | null (date-time)required
  • ach_generated_at
    string | null (date-time)required
    When the NACHA file was last generated (null: never).
  • ach_file_id_modifier
    string | nullrequired
    File id modifier of the last NACHA file: A, then B, C… on each audited re-send.
  • total
    stringrequired
    Money, 2 dp
  • payment_count
    integerrequired
  • payments
    object[]required
  • payments[].id
    integerrequired
  • payments[].run_id
    integer | nullrequired
  • payments[].vendor_id
    integerrequired
  • payments[].vendor_name
    string | nullrequired
  • payments[].entity_id
    integerrequired
  • payments[].method
    stringrequired
    One of: check, ach, wire, virtual_card, owner_direct.
  • payments[].check_number
    string | nullrequired
  • payments[].payment_date
    string (date)required
  • payments[].cash_account_id
    integerrequired
  • payments[].amount
    stringrequired
    Money, 2 dp
  • payments[].discount_amount
    stringrequired
    Money, 2 dp
  • payments[].withholding_amount
    stringrequired
    Money, 2 dp
  • payments[].joint_payees
    object[]required
  • payments[].customer_id
    integer | nullrequired
  • payments[].status
    stringrequired
    One of: draft, posted, void.
  • payments[].memo
    string | nullrequired
  • payments[].entry_id
    integer | nullrequired
  • payments[].voided_at
    string | null (date-time)required
  • payments[].void_entry_id
    integer | nullrequired
  • payments[].void_reason
    string | nullrequired
  • payments[].ach_trace_number
    string | nullrequired
    ACH: trace number in the last generated NACHA file.
  • payments[].applications
    object[]required
  • payments[].created_at
    string (date-time)required
  • created_at
    string (date-time)required
  • ach_resend_requested_by_id
    integer | null
    Pending requester; null when there is no pending resend.
  • ach_resend_reason
    string | null

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)
  • 422Validation failed or the ledger refused the change

Example request

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • run_id
    integer | nullrequired
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • entity_id
    integerrequired
  • method
    stringrequired
    One of: check, ach, wire, virtual_card, owner_direct.
  • check_number
    string | nullrequired
  • payment_date
    string (date)required
  • cash_account_id
    integerrequired
  • amount
    stringrequired
    Money, 2 dp
  • discount_amount
    stringrequired
    Money, 2 dp
  • withholding_amount
    stringrequired
    Money, 2 dp
  • joint_payees
    object[]required
  • joint_payees[].name
    stringrequired
  • joint_payees[].amount
    stringrequired
  • customer_id
    integer | nullrequired
  • status
    stringrequired
    One of: draft, posted, void.
  • memo
    string | nullrequired
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • ach_trace_number
    string | nullrequired
    ACH: trace number in the last generated NACHA file.
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].bill_id
    integerrequired
  • applications[].payment_id
    integer | nullrequired
  • applications[].credit_id
    integer | nullrequired
  • applications[].date
    string (date)required
  • applications[].amount
    stringrequired
    Money, 2 dp
  • applications[].discount
    stringrequired
    Money, 2 dp
  • applications[].withholding
    stringrequired
    Money, 2 dp
  • applications[].voided
    booleanrequired
  • applications[].bill_number
    stringrequired
  • applications[].invoice_number
    string | nullrequired
  • created_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • payment_id
    integerrequired
  • subject
    stringrequired
  • text
    stringrequired
  • content_sha256
    string
  • totals
    objectrequired
  • totals.applied
    stringrequired
  • totals.discount
    stringrequired
  • totals.withholding
    stringrequired
  • totals.net
    stringrequired
  • totals.retainage_held
    stringrequired
  • sends
    object[]required
  • sends[].id
    integer
  • sends[].recipient
    string | null
  • sends[].status
    string
    One of: sent, failed, no_recipient.
  • sends[].resend
    boolean
  • sends[].email_message_id
    integer | null
  • sends[].content_sha256
    string
  • sends[].created_at
    string (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • remittance
    objectrequired
  • remittance.to
    string (email)

Response · 200 · object

  • payment_id
    integerrequired
  • subject
    stringrequired
  • text
    stringrequired
  • content_sha256
    string
  • totals
    objectrequired
  • totals.applied
    stringrequired
  • totals.discount
    stringrequired
  • totals.withholding
    stringrequired
  • totals.net
    stringrequired
  • totals.retainage_held
    stringrequired
  • sends
    object[]required
  • sends[].id
    integer
  • sends[].recipient
    string | null
  • sends[].status
    string
    One of: sent, failed, no_recipient.
  • sends[].resend
    boolean
  • sends[].email_message_id
    integer | null
  • sends[].content_sha256
    string
  • sends[].created_at
    string (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed

Example request

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

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • payment_id
    integerrequired
  • entity_id
    integer
  • vendor
    object
  • vendor.id
    integer
  • vendor.name
    string | null
  • provider
    string
  • status
    stringrequired
    One of: pending_issue, issued, issue_failed, settled, settlement_mismatch, canceled.
  • last4
    string | null
  • exp_month
    integer | null
  • exp_year
    integer | null
  • amount
    stringrequired
  • currency
    stringrequired
  • issued_at
    string | null (date-time)
  • settlement_id
    string | null
  • settled_amount
    string | null
  • settled_on
    string | null (date)
  • bank_transaction_id
    integer | null
  • error
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (state guard)
  • 503No usable card provider

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • void
    objectrequired
  • void.date
    string (date)required
  • void.reason
    stringrequired
  • void.confirm_ach_recalled
    boolean
    Required true to void an ACH payment that was already transmitted (the bank recalled or returned it).

Response · 200 · object

  • id
    integerrequired
  • run_id
    integer | nullrequired
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • entity_id
    integerrequired
  • method
    stringrequired
    One of: check, ach, wire, virtual_card, owner_direct.
  • check_number
    string | nullrequired
  • payment_date
    string (date)required
  • cash_account_id
    integerrequired
  • amount
    stringrequired
    Money, 2 dp
  • discount_amount
    stringrequired
    Money, 2 dp
  • withholding_amount
    stringrequired
    Money, 2 dp
  • joint_payees
    object[]required
  • joint_payees[].name
    stringrequired
  • joint_payees[].amount
    stringrequired
  • customer_id
    integer | nullrequired
  • status
    stringrequired
    One of: draft, posted, void.
  • memo
    string | nullrequired
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • ach_trace_number
    string | nullrequired
    ACH: trace number in the last generated NACHA file.
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].bill_id
    integerrequired
  • applications[].payment_id
    integer | nullrequired
  • applications[].credit_id
    integer | nullrequired
  • applications[].date
    string (date)required
  • applications[].amount
    stringrequired
    Money, 2 dp
  • applications[].discount
    stringrequired
    Money, 2 dp
  • applications[].withholding
    stringrequired
    Money, 2 dp
  • applications[].voided
    booleanrequired
  • applications[].bill_number
    stringrequired
  • applications[].invoice_number
    string | nullrequired
  • created_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)
  • 422Validation failed or the ledger refused the change

Example request

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

List PO receipts

Filter by commitment_id. Limited to the caller's entities. Paginated. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • number
    stringrequired
  • commitment_id
    integerrequired
  • project_id
    integerrequired
  • vendor_id
    integerrequired
  • entity_id
    integer | nullrequired
  • receipt_date
    string (date)required
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • lines
    object[]required
  • lines[].id
    integerrequired
  • lines[].commitment_line_item_id
    integerrequired
  • lines[].quantity
    stringrequired
  • lines[].amount
    stringrequired
    Money, 2 dp
  • created_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/receipts" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Payable

POST /rest/v1.0/companies/{company_id}/accounting/ap/receipts

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

v1.0Implemented

Parameters

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

Request body

  • receipt
    objectrequired
  • receipt.commitment_id
    integerrequired
  • receipt.entity_id
    integer | null
    Must match the project's assigned entity when it has one; defaults to it, else to the default entity.
  • receipt.receipt_date
    string (date)required
  • receipt.lines
    object[]required
  • receipt.lines[].commitment_line_item_id
    integerrequired
  • receipt.lines[].quantity
    stringrequired
    Greater than zero; with earlier receipts that are not void, at most the PO line quantity (422 over_received).
  • receipt.lines[].account_id
    integer | null
    Cost account the accrual debits (postable, not a control account). Defaults to the first material job cost account.

Response · 201 · object

  • id
    integerrequired
  • number
    stringrequired
  • commitment_id
    integerrequired
  • project_id
    integerrequired
  • vendor_id
    integerrequired
  • entity_id
    integer | nullrequired
  • receipt_date
    string (date)required
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • lines
    object[]required
  • lines[].id
    integerrequired
  • lines[].commitment_line_item_id
    integerrequired
  • lines[].quantity
    stringrequired
  • lines[].amount
    stringrequired
    Money, 2 dp
  • created_at
    string (date-time)required

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed (over_received, zero quantity, entity mismatch) or the ledger refused the change

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • void
    objectrequired
  • void.date
    string (date)required
  • void.reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • commitment_id
    integerrequired
  • project_id
    integerrequired
  • vendor_id
    integerrequired
  • entity_id
    integer | nullrequired
  • receipt_date
    string (date)required
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • lines
    object[]required
  • lines[].id
    integerrequired
  • lines[].commitment_line_item_id
    integerrequired
  • lines[].quantity
    stringrequired
  • lines[].amount
    stringrequired
    Money, 2 dp
  • created_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (receipt_invoiced: posted bills invoiced the quantities it received)
  • 422Validation failed or the ledger refused the change

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • void
    objectrequired
  • void.date
    string (date)required
  • void.reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • kind
    stringrequired
    One of: bill, credit.
  • status
    stringrequired
    One of: draft, pending_approval, posted, void.
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • entity_id
    integerrequired
  • invoice_number
    string | nullrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • term_id
    integer | nullrequired
  • discount_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • discount_date
    string | null (date)required
  • memo
    string | nullrequired
  • total
    stringrequired
    Money, 2 dp
  • retainage_amount
    stringrequired
    Money, 2 dp
  • use_tax_amount
    stringrequired
    Money, 2 dp
  • tax_code_id
    integer | nullrequired
  • open_amount
    stringrequired
    Money, 2 dp
  • retainage_open
    stringrequired
    Money, 2 dp
  • paid_amount
    stringrequired
    Money, 2 dp
  • retainage_released
    stringrequired
    Money, 2 dp
  • commitment_type
    string | nullrequired
  • commitment_id
    integer | nullrequired
  • requisition_id
    integer | nullrequired
  • direct_cost_id
    integer | nullrequired
  • pay_when_paid_pay_app_id
    integer | nullrequired
  • pay_when_paid_mode
    string | nullrequired
  • off_rent_date
    string | null (date)required
  • billed_through
    string | null (date)required
  • match
    object | nullrequired
  • hold_overrides
    object[]required
  • revision
    integerrequired
  • prepared_by_id
    integerrequired
  • last_edited_by_id
    integerrequired
  • contributor_ids
    integer[]required
    Every user who created or edited the bill. None of them may approve it, override its holds or release its payment.
  • submitted_at
    string | null (date-time)required
  • approved_at
    string | null (date-time)required
  • entry_id
    integer | nullrequired
  • voided_at
    string | null (date-time)required
  • void_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • lines
    object[]required
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].description
    string | nullrequired
  • lines[].amount
    stringrequired
    Money, 2 dp
  • lines[].retainage_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].retainage_amount
    stringrequired
    Money, 2 dp
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].equipment_id
    integer | nullrequired
  • lines[].commitment_line_item_id
    integer | nullrequired
  • lines[].quantity
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].unit_price
    string | nullrequired
    Rate/quantity, 6 dp
  • lines[].use_tax
    booleanrequired
  • lines[].reportable_1099
    booleanrequired
  • lines[].tax_category
    string | nullrequired
    Contractor 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_ids
    array | nullrequired
    User-defined dimension values (AcctDimensionValue ids).
  • holds
    object[]required
  • holds[].code
    stringrequired
    Hold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
  • holds[].message
    stringrequired
  • holds[].overridden
    booleanrequired
  • approvals_required
    integerrequired
  • route_preview
    stringrequired
  • approvals
    object[]required
  • approvals[].user_id
    integerrequired
  • approvals[].step
    integerrequired
  • approvals[].approved_at
    string (date-time)required
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].bill_id
    integerrequired
  • applications[].payment_id
    integer | nullrequired
  • applications[].credit_id
    integer | nullrequired
  • applications[].date
    string (date)required
  • applications[].amount
    stringrequired
    Money, 2 dp
  • applications[].discount
    stringrequired
    Money, 2 dp
  • applications[].withholding
    stringrequired
    Money, 2 dp
  • applications[].voided
    booleanrequired
  • retainage_releases
    object[]required
  • retainage_releases[].id
    integerrequired
  • retainage_releases[].date
    string (date)required
  • retainage_releases[].amount
    stringrequired
    Money, 2 dp
  • retainage_releases[].entry_id
    integerrequired
  • retainage_releases[].voided_at
    string | null (date)
    Effective void date; as-of aging counts the release before it.
  • retainage_releases[].void_entry_id
    integer | null
  • retainage_releases[].void_reason
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)
  • 422Validation failed or the ledger refused the change

Example request

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

AP settings

Matching tolerances, over-commitment action, discount posting, approval bands, hold settings and the default pay-from cash account. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • over_commitment_action
    stringrequired
  • match_tolerance_pct
    stringrequired
  • match_tolerance_amount
    stringrequired
    Money, 2 dp
  • receipt_accrual
    booleanrequired
  • discount_posting_mode
    stringrequired
  • bank_change_hold_days
    integerrequired
  • lien_waiver_mode
    stringrequired
  • approval_bands
    object[]required
  • approval_bands[].min
    stringrequired
  • approval_bands[].approvals
    integerrequired
  • approval_bands[].final_role
    string | null
  • rni_account_id
    integer | nullrequired
  • backup_withholding_account_id
    integer | nullrequired
  • cash_account_id
    integer | nullrequired
    Default 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_id
    string | nullrequired
  • ach_company_name
    string | nullrequired
  • ach_destination_routing
    string | nullrequired
  • ach_destination_name
    string | nullrequired
  • prompt_pay_days
    integer | nullrequired
  • updated_at
    string (date-time)required
  • backup_withholding_policy
    stringrequired
    hold: 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_pct
    stringrequired
    Three-way match quantity tolerance: percent of received-not-invoiced. Both this and match_qty_tolerance must hold (whichever is less). Default 0.
  • match_qty_tolerance
    stringrequired
    Three-way match quantity tolerance as an absolute quantity. Default 0 (no quantity tolerance).
  • match_cost_type_tolerances
    object[]required
    Per 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_id
    integerrequired
  • match_cost_type_tolerances[].price_pct
    string | null
  • match_cost_type_tolerances[].price_amount
    string | null
  • match_cost_type_tolerances[].qty_pct
    string | null
  • match_cost_type_tolerances[].qty
    string | null
  • match_receipt_policy
    stringrequired
    When 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_po
    booleanrequired
    Job-coded bill lines with no purchase order or subcontract are no_po exceptions. Default false.
  • ach_prenote_required
    booleanrequired
    Payment 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 token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/settings" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Payable

PATCH /rest/v1.0/companies/{company_id}/accounting/ap/settings

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

v1.0Implemented

Parameters

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

Request body

  • ap_settings
    objectrequired
  • ap_settings.approval_bands
    object[]
  • ap_settings.approval_bands[].min
    stringrequired
  • ap_settings.approval_bands[].approvals
    integerrequired
  • ap_settings.approval_bands[].final_role
    string | null
  • ap_settings.bank_change_hold_days
    integer
    Vendor bank-change cool-off in days; never below 3. Changing it needs manage_grants.
  • ap_settings.backup_withholding_policy
    string
    One of: withhold, hold.
  • ap_settings.match_qty_tolerance_pct
    string
    Three-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_tolerance
    string
    Three-way match quantity tolerance as an absolute quantity. Default 0 (no quantity tolerance).
  • ap_settings.match_cost_type_tolerances
    object[]
    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_id
    integerrequired
  • ap_settings.match_cost_type_tolerances[].price_pct
    string | null
  • ap_settings.match_cost_type_tolerances[].price_amount
    string | null
  • ap_settings.match_cost_type_tolerances[].qty_pct
    string | null
  • ap_settings.match_cost_type_tolerances[].qty
    string | null
  • ap_settings.match_receipt_policy
    string
    When 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_po
    boolean
    Job-coded bill lines with no purchase order or subcontract are no_po exceptions. Default false.
  • ap_settings.ach_prenote_required
    boolean

Response · 200 · object

  • over_commitment_action
    stringrequired
  • match_tolerance_pct
    stringrequired
  • match_tolerance_amount
    stringrequired
    Money, 2 dp
  • receipt_accrual
    booleanrequired
  • discount_posting_mode
    stringrequired
  • bank_change_hold_days
    integerrequired
  • lien_waiver_mode
    stringrequired
  • approval_bands
    object[]required
  • approval_bands[].min
    stringrequired
  • approval_bands[].approvals
    integerrequired
  • approval_bands[].final_role
    string | null
  • rni_account_id
    integer | nullrequired
  • backup_withholding_account_id
    integer | nullrequired
  • cash_account_id
    integer | nullrequired
    Default 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_id
    string | nullrequired
  • ach_company_name
    string | nullrequired
  • ach_destination_routing
    string | nullrequired
  • ach_destination_name
    string | nullrequired
  • prompt_pay_days
    integer | nullrequired
  • updated_at
    string (date-time)required
  • backup_withholding_policy
    stringrequired
    hold: 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_pct
    stringrequired
    Three-way match quantity tolerance: percent of received-not-invoiced. Both this and match_qty_tolerance must hold (whichever is less). Default 0.
  • match_qty_tolerance
    stringrequired
    Three-way match quantity tolerance as an absolute quantity. Default 0 (no quantity tolerance).
  • match_cost_type_tolerances
    object[]required
    Per 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_id
    integerrequired
  • match_cost_type_tolerances[].price_pct
    string | null
  • match_cost_type_tolerances[].price_amount
    string | null
  • match_cost_type_tolerances[].qty_pct
    string | null
  • match_cost_type_tolerances[].qty
    string | null
  • match_receipt_policy
    stringrequired
    When 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_po
    booleanrequired
    Job-coded bill lines with no purchase order or subcontract are no_po exceptions. Default false.
  • ach_prenote_required
    booleanrequired
    Payment 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 token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed or the ledger refused the change

Example request

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

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • as_of
    string (date)query
  • entity_id
    integerquery
    One entity inside the caller's grant; default every entity the grant allows.

Response · 200 · object

  • as_of
    string (date)required
  • ap
    objectrequired
  • ap.subledger
    stringrequired
    Money, 2 dp
  • ap.control
    stringrequired
    Money, 2 dp
  • ap.difference
    stringrequired
    Money, 2 dp
  • retainage
    objectrequired
  • retainage.subledger
    stringrequired
    Money, 2 dp
  • retainage.control
    stringrequired
    Money, 2 dp
  • retainage.difference
    stringrequired
    Money, 2 dp
  • in_balance
    booleanrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/tie_out" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Payable

POST /rest/v1.0/companies/{company_id}/accounting/ap/tin_matching/export

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • filename
    stringrequired
  • records
    integerrequired
  • text
    stringrequired
  • skipped
    object[]required
  • skipped[].vendor_id
    integer
  • skipped[].reason
    string

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 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

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

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

v1.0Implemented

Parameters

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

Request body

  • tin_matching
    objectrequired
  • tin_matching.text
    stringrequired
  • tin_matching.matched_at
    string (date)required

Response · 200 · object

  • applied
    object[]required
  • applied[].vendor_id
    integer
  • applied[].code
    integer
  • applied[].status
    string
    One of: matched, mismatch, resubmit.
  • applied[].hold
    boolean
  • skipped
    object[]required
  • skipped[].line
    integer
  • skipped[].account
    string
  • skipped[].reason
    string
    One of: unknown_vendor, stale_tin.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 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

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

List portal bank change requests

Needs manage_vendor_banking. Last four digits only. Filter status (pending_review, forwarded, rejected). Paginated. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • vendor_id
    integerrequired
  • portal_grant_id
    integer
  • status
    stringrequired
    One of: pending_review, forwarded, rejected.
  • routing_last4
    stringrequired
  • account_last4
    stringrequired
  • account_type
    stringrequired
    One of: checking, savings.
  • note
    string | null
  • forwarded_by_id
    integer | null
  • forwarded_at
    string | null (date-time)
  • change_hash
    string | null
  • reviewed_by_id
    integer | null
  • reviewed_at
    string | null (date-time)
  • review_note
    string | null
  • created_at
    string (date-time)
  • party_profile_id
    integer

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 422Validation failed

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • review
    objectrequired
  • review.note
    string | null

Response · 200 · object

  • id
    integerrequired
  • vendor_id
    integerrequired
  • portal_grant_id
    integer
  • status
    stringrequired
    One of: pending_review, forwarded, rejected.
  • routing_last4
    stringrequired
  • account_last4
    stringrequired
  • account_type
    stringrequired
    One of: checking, savings.
  • note
    string | null
  • forwarded_by_id
    integer | null
  • forwarded_at
    string | null (date-time)
  • change_hash
    string | null
  • reviewed_by_id
    integer | null
  • reviewed_at
    string | null (date-time)
  • review_note
    string | null
  • created_at
    string (date-time)
  • party_profile_id
    integer

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (state guard)
  • 422Validation failed

Example request

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

Reject a bank change request

Needs manage_vendor_banking and a note. The sealed numbers are discarded. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • review
    objectrequired
  • review.note
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • vendor_id
    integerrequired
  • portal_grant_id
    integer
  • status
    stringrequired
    One of: pending_review, forwarded, rejected.
  • routing_last4
    stringrequired
  • account_last4
    stringrequired
  • account_type
    stringrequired
    One of: checking, savings.
  • note
    string | null
  • forwarded_by_id
    integer | null
  • forwarded_at
    string | null (date-time)
  • change_hash
    string | null
  • reviewed_by_id
    integer | null
  • reviewed_at
    string | null (date-time)
  • review_note
    string | null
  • created_at
    string (date-time)
  • party_profile_id
    integer

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (state guard)
  • 422Validation failed

Example request

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

List vendor portal users

Active and revoked grants. Filter vendor_id. Paginated. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • vendor_id
    integerrequired
  • role
    stringrequired
    One of: member, admin.
  • email
    stringrequired
  • name
    string
  • active
    booleanrequired
  • granted_at
    string (date-time)
  • revoked_at
    string | null (date-time)
  • revocation_note
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/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}/revoke

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

v1.0Implemented

Parameters

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

Request body

  • revoke
    objectrequired
  • revoke.note
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • vendor_id
    integerrequired
  • role
    stringrequired
    One of: member, admin.
  • email
    stringrequired
  • name
    string
  • active
    booleanrequired
  • granted_at
    string (date-time)
  • revoked_at
    string | null (date-time)
  • revocation_note
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed

Example request

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

List vendor portal invitations

Filter vendor_id. Paginated. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • vendor_id
    integerrequired
  • email
    stringrequired
  • name
    string
  • role
    stringrequired
    One of: member, admin.
  • expires_at
    string (date-time)
  • accepted_at
    string | null (date-time)
  • revoked_at
    string | null (date-time)
  • revocation_note
    string | null
  • created_by_id
    integer
  • created_at
    string (date-time)
  • status
    stringrequired
    One of: pending, accepted, revoked, expired.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendor_portal/invitations" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Payable

POST /rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/invitations

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

v1.0Implemented

Parameters

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

Request body

  • invitation
    objectrequired
  • invitation.vendor_id
    integerrequired
  • invitation.email
    string (email)required
  • invitation.name
    stringrequired
  • invitation.role
    string
    One of: member, admin.

Response · 201 · object

  • id
    integerrequired
  • vendor_id
    integerrequired
  • email
    stringrequired
  • name
    string
  • role
    stringrequired
    One of: member, admin.
  • expires_at
    string (date-time)
  • accepted_at
    string | null (date-time)
  • revoked_at
    string | null (date-time)
  • revocation_note
    string | null
  • created_by_id
    integer
  • created_at
    string (date-time)
  • status
    stringrequired
    One of: pending, accepted, revoked, expired.
  • secret
    stringrequired
    The one-time activation secret. Shown only in this response; deliver it to the invitee out of band.
  • activation_url
    string

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (state guard)
  • 422Validation failed

Example request

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

Revoke a pending invitation

Needs ap_approve and a note. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • revoke
    objectrequired
  • revoke.note
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • vendor_id
    integerrequired
  • email
    stringrequired
  • name
    string
  • role
    stringrequired
    One of: member, admin.
  • expires_at
    string (date-time)
  • accepted_at
    string | null (date-time)
  • revoked_at
    string | null (date-time)
  • revocation_note
    string | null
  • created_by_id
    integer
  • created_at
    string (date-time)
  • status
    stringrequired
    One of: pending, accepted, revoked, expired.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed

Example request

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

List portal compliance submissions

COIs and lien waivers uploaded through the portal. Filter status (pending, accepted, rejected). Paginated. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • vendor_id
    integerrequired
  • portal_grant_id
    integer
  • kind
    stringrequired
    One of: coi, lien_waiver.
  • status
    stringrequired
    One of: pending, accepted, rejected.
  • details
    object
  • file
    objectrequired
  • file.name
    string
  • file.content_type
    string
  • file.size_bytes
    integer
  • file.sha256
    string
  • file.scan_status
    string
  • file.download_url
    string | null
  • compliance_id
    integer | null
  • lien_waiver_id
    integer | null
  • reviewed_by_id
    integer | null
  • reviewed_at
    string | null (date-time)
  • review_note
    string | null
  • created_at
    string (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 422Validation failed

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • review
    objectrequired
  • review.note
    string
  • review.project_id
    integer | null
  • review.payment_id
    integer | null
  • review.received_at
    string (date)

Response · 200 · object

  • id
    integerrequired
  • vendor_id
    integerrequired
  • portal_grant_id
    integer
  • kind
    stringrequired
    One of: coi, lien_waiver.
  • status
    stringrequired
    One of: pending, accepted, rejected.
  • details
    object
  • file
    objectrequired
  • file.name
    string
  • file.content_type
    string
  • file.size_bytes
    integer
  • file.sha256
    string
  • file.scan_status
    string
  • file.download_url
    string | null
  • compliance_id
    integer | null
  • lien_waiver_id
    integer | null
  • reviewed_by_id
    integer | null
  • reviewed_at
    string | null (date-time)
  • review_note
    string | null
  • created_at
    string (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (state guard)
  • 422Validation failed

Example request

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

Reject a portal compliance submission

Needs ap_enter and a note the vendor sees. 409 not_pending. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • review
    objectrequired
  • review.note
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • vendor_id
    integerrequired
  • portal_grant_id
    integer
  • kind
    stringrequired
    One of: coi, lien_waiver.
  • status
    stringrequired
    One of: pending, accepted, rejected.
  • details
    object
  • file
    objectrequired
  • file.name
    string
  • file.content_type
    string
  • file.size_bytes
    integer
  • file.sha256
    string
  • file.scan_status
    string
  • file.download_url
    string | null
  • compliance_id
    integer | null
  • lien_waiver_id
    integer | null
  • reviewed_by_id
    integer | null
  • reviewed_at
    string | null (date-time)
  • review_note
    string | null
  • created_at
    string (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict (state guard)
  • 422Validation failed

Example request

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

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

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • vendor_id
    integerrequired
  • name
    string | nullrequired
  • is_1099
    booleanrequired
  • w9_status
    stringrequired
  • payment_method
    stringrequired
  • compliance_hold
    booleanrequired
  • coi_expires_at
    string | null (date)required
  • coi_expired
    booleanrequired
  • stop_pay
    booleanrequired
  • open_balance
    stringrequired
    Money, 2 dp
  • retainage_held
    stringrequired
    Money, 2 dp

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/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.

v1.0Implemented

Parameters

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

Response · 200 · object

  • vendor_id
    integerrequired
  • name
    stringrequired
  • profile_id
    integer | nullrequired
  • is_1099
    booleanrequired
  • w9_status
    string | nullrequired
  • compliance_hold
    booleanrequired
  • compliance
    object[]required
  • compliance[].id
    integerrequired
  • compliance[].vendor_id
    integerrequired
  • compliance[].kind
    stringrequired
    One of: coi, w9, license, prequalification, stop_pay.
  • compliance[].reference
    string | nullrequired
  • compliance[].effective_at
    string | null (date)required
  • compliance[].expires_at
    string | null (date)required
  • compliance[].active
    booleanrequired
  • compliance[].notes
    string | nullrequired
  • compliance[].created_at
    string (date-time)required
  • lien_waivers
    object[]required
  • lien_waivers[].id
    integerrequired
  • lien_waivers[].vendor_id
    integerrequired
  • lien_waivers[].project_id
    integer | nullrequired
  • lien_waivers[].party
    stringrequired
  • lien_waivers[].kind
    stringrequired
  • lien_waivers[].scope
    stringrequired
  • lien_waivers[].payment_no
    integerrequired
  • lien_waivers[].through_date
    string | null (date)required
  • lien_waivers[].amount
    string | nullrequired
  • lien_waivers[].received_at
    string (date)required
  • lien_waivers[].created_at
    string (date-time)required
  • lien_waivers[].payment_id
    integer | nullrequired
  • bills
    object[]required
  • bills[].id
    integerrequired
  • bills[].number
    stringrequired
  • bills[].kind
    stringrequired
    One of: bill, credit.
  • bills[].status
    stringrequired
    One of: draft, pending_approval, posted, void.
  • bills[].vendor_id
    integerrequired
  • bills[].vendor_name
    string | nullrequired
  • bills[].entity_id
    integerrequired
  • bills[].invoice_number
    string | nullrequired
  • bills[].invoice_date
    string (date)required
  • bills[].posting_date
    string (date)required
  • bills[].due_date
    string (date)required
  • bills[].term_id
    integer | nullrequired
  • bills[].discount_percent
    string | nullrequired
    Rate/quantity, 6 dp
  • bills[].discount_date
    string | null (date)required
  • bills[].memo
    string | nullrequired
  • bills[].total
    stringrequired
    Money, 2 dp
  • bills[].retainage_amount
    stringrequired
    Money, 2 dp
  • bills[].use_tax_amount
    stringrequired
    Money, 2 dp
  • bills[].tax_code_id
    integer | nullrequired
  • bills[].open_amount
    stringrequired
    Money, 2 dp
  • bills[].retainage_open
    stringrequired
    Money, 2 dp
  • bills[].paid_amount
    stringrequired
    Money, 2 dp
  • bills[].retainage_released
    stringrequired
    Money, 2 dp
  • bills[].commitment_type
    string | nullrequired
  • bills[].commitment_id
    integer | nullrequired
  • bills[].requisition_id
    integer | nullrequired
  • bills[].direct_cost_id
    integer | nullrequired
  • bills[].pay_when_paid_pay_app_id
    integer | nullrequired
  • bills[].pay_when_paid_mode
    string | nullrequired
  • bills[].off_rent_date
    string | null (date)required
  • bills[].billed_through
    string | null (date)required
  • bills[].match
    object | nullrequired
  • bills[].hold_overrides
    object[]required
  • bills[].revision
    integerrequired
  • bills[].prepared_by_id
    integerrequired
  • bills[].last_edited_by_id
    integerrequired
  • bills[].contributor_ids
    integer[]required
    Every user who created or edited the bill. None of them may approve it, override its holds or release its payment.
  • bills[].submitted_at
    string | null (date-time)required
  • bills[].approved_at
    string | null (date-time)required
  • bills[].entry_id
    integer | nullrequired
  • bills[].voided_at
    string | null (date-time)required
  • bills[].void_entry_id
    integer | nullrequired
  • bills[].void_reason
    string | nullrequired
  • bills[].created_at
    string (date-time)required
  • bills[].updated_at
    string (date-time)required
  • bills[].lines
    object[]

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

List attachments on a vendor

Oldest first. Needs view_ledger and the parent's entity scope. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • doc_type
    stringrequired
    One 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_id
    integerrequired
  • name
    stringrequired
  • content_type
    stringrequired
  • size_bytes
    integerrequired
  • sha256
    stringrequired
  • uploaded_by
    objectrequired
  • uploaded_by.id
    integerrequired
  • uploaded_by.name
    string | nullrequired
  • created_at
    string (date-time)required
  • download_url
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • file
    string (binary)required

Response · 201 · object

  • id
    integerrequired
  • doc_type
    stringrequired
    One 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_id
    integerrequired
  • name
    stringrequired
  • content_type
    stringrequired
  • size_bytes
    integerrequired
  • sha256
    stringrequired
  • uploaded_by
    objectrequired
  • uploaded_by.id
    integerrequired
  • uploaded_by.name
    string | nullrequired
  • created_at
    string (date-time)required
  • download_url
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Idempotency-Key reused for a different request or still in progress
  • 413Request body too large
  • 422Missing file, empty file, too large, or a type that is not allowed

Example request

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

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • vendor_id
    integerrequired
  • remittance_email
    string | null
  • sender_addresses
    string[]required
  • updated_at
    string | null (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

Update a vendor's remittance and capture settings

Needs ap_enter. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • vendor_automation
    objectrequired
  • vendor_automation.remittance_email
    string | null (email)
  • vendor_automation.sender_addresses
    string[]

Response · 200 · object

  • vendor_id
    integerrequired
  • remittance_email
    string | null
  • sender_addresses
    string[]required
  • updated_at
    string | null (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • compliance
    objectrequired
  • compliance.kind
    stringrequired
  • compliance.reference
    string | null
  • compliance.effective_at
    string | null (date)
  • compliance.expires_at
    string | null (date)
  • compliance.notes
    string | null

Response · 201 · object

  • id
    integerrequired
  • vendor_id
    integerrequired
  • kind
    stringrequired
    One of: coi, w9, license, prequalification, stop_pay.
  • reference
    string | nullrequired
  • effective_at
    string | null (date)required
  • expires_at
    string | null (date)required
  • active
    booleanrequired
  • notes
    string | nullrequired
  • created_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed or the ledger refused the change

Example request

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

v1.0Implemented

Parameters

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

Request body

  • compliance
    objectrequired
  • compliance.active
    booleanrequired

Response · 200 · object

  • id
    integerrequired
  • vendor_id
    integerrequired
  • kind
    stringrequired
    One of: coi, w9, license, prequalification, stop_pay.
  • reference
    string | nullrequired
  • effective_at
    string | null (date)required
  • expires_at
    string | null (date)required
  • active
    booleanrequired
  • notes
    string | nullrequired
  • created_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed or the ledger refused the change

Example request

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

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

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • doc_type
    stringrequired
    One 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_id
    integerrequired
  • name
    stringrequired
  • content_type
    stringrequired
  • size_bytes
    integerrequired
  • sha256
    stringrequired
  • uploaded_by
    objectrequired
  • uploaded_by.id
    integerrequired
  • uploaded_by.name
    string | nullrequired
  • created_at
    string (date-time)required
  • download_url
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • file
    string (binary)required

Response · 201 · object

  • id
    integerrequired
  • doc_type
    stringrequired
    One 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_id
    integerrequired
  • name
    stringrequired
  • content_type
    stringrequired
  • size_bytes
    integerrequired
  • sha256
    stringrequired
  • uploaded_by
    objectrequired
  • uploaded_by.id
    integerrequired
  • uploaded_by.name
    string | nullrequired
  • created_at
    string (date-time)required
  • download_url
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Idempotency-Key reused for a different request or still in progress
  • 413Request body too large
  • 422Missing file, empty file, too large, or a type that is not allowed

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • lien_waiver
    objectrequired
  • lien_waiver.project_id
    integer | null
  • lien_waiver.party
    string
  • lien_waiver.kind
    stringrequired
  • lien_waiver.scope
    stringrequired
  • lien_waiver.payment_no
    integer
    Required unless payment_id is given
  • lien_waiver.through_date
    string | null (date)
  • lien_waiver.amount
    string | null
  • lien_waiver.received_at
    string (date)required
  • lien_waiver.payment_id
    integer | null
    Posted AP payment the waiver covers

Response · 201 · object

  • id
    integerrequired
  • vendor_id
    integerrequired
  • project_id
    integer | nullrequired
  • party
    stringrequired
  • kind
    stringrequired
  • scope
    stringrequired
  • payment_no
    integerrequired
  • through_date
    string | null (date)required
  • amount
    string | nullrequired
  • received_at
    string (date)required
  • created_at
    string (date-time)required
  • payment_id
    integer | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed or the ledger refused the change

Example request

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

List attachments on a lien waiver

Oldest first. Needs view_ledger and the parent's entity scope. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • doc_type
    stringrequired
    One 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_id
    integerrequired
  • name
    stringrequired
  • content_type
    stringrequired
  • size_bytes
    integerrequired
  • sha256
    stringrequired
  • uploaded_by
    objectrequired
  • uploaded_by.id
    integerrequired
  • uploaded_by.name
    string | nullrequired
  • created_at
    string (date-time)required
  • download_url
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • file
    string (binary)required

Response · 201 · object

  • id
    integerrequired
  • doc_type
    stringrequired
    One 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_id
    integerrequired
  • name
    stringrequired
  • content_type
    stringrequired
  • size_bytes
    integerrequired
  • sha256
    stringrequired
  • uploaded_by
    objectrequired
  • uploaded_by.id
    integerrequired
  • uploaded_by.name
    string | nullrequired
  • created_at
    string (date-time)required
  • download_url
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Idempotency-Key reused for a different request or still in progress
  • 413Request body too large
  • 422Missing file, empty file, too large, or a type that is not allowed

Example request

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

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

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • payment_id
    integerrequired
  • entity_id
    integer
  • vendor
    object
  • vendor.id
    integer
  • vendor.name
    string | null
  • provider
    string
  • status
    stringrequired
    One of: pending_issue, issued, issue_failed, settled, settlement_mismatch, canceled.
  • last4
    string | null
  • exp_month
    integer | null
  • exp_year
    integer | null
  • amount
    stringrequired
  • currency
    stringrequired
  • issued_at
    string | null (date-time)
  • settlement_id
    string | null
  • settled_amount
    string | null
  • settled_on
    string | null (date)
  • bank_transaction_id
    integer | null
  • error
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 422Validation failed

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • sync
    object

Response · 200 · object

  • settled
    integerrequired
  • matched
    integerrequired
  • mismatched
    integerrequired
  • skipped
    integerrequired
  • blocked
    integer
    Settlements 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.
  • errors
    object[]
  • errors[].settlement_id
    stringrequired
  • errors[].message
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed
  • 503No usable card provider

Example request

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

Ask the OS

Reading this page

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

Suggested

    AI · may be imperfect · sample data where shown

    Open file