Esc

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

Accounts Receivable

Invoice customers, manage retainage, apply receipts and follow collections. 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 Receivable guide for the workflow.

78 operationsCompany moduleAll Accounting apps →
  1. GET /rest/v1.0/companies/{company_id}/accounting/ar/collections/disputesDisputes
  2. POST /rest/v1.0/companies/{company_id}/accounting/ar/collections/disputesOpen a dispute on a posted invoice (arEnter)
  3. GET /rest/v1.0/companies/{company_id}/accounting/ar/collections/disputes/{id}A dispute
  4. POST /rest/v1.0/companies/{company_id}/accounting/ar/collections/disputes/{id}/resolveResolve or withdraw a dispute (arEnter)
  5. GET /rest/v1.0/companies/{company_id}/accounting/ar/collections/paymentsOnline payments
  6. GET /rest/v1.0/companies/{company_id}/accounting/ar/collections/payments/{id}An online payment
  7. GET /rest/v1.0/companies/{company_id}/accounting/ar/collections/policiesDunning policies
  8. POST /rest/v1.0/companies/{company_id}/accounting/ar/collections/policiesCreate a dunning policy (arApprove)
  9. PATCH /rest/v1.0/companies/{company_id}/accounting/ar/collections/policies/{id}Replace a dunning policy's cadence (arApprove)
  10. GET /rest/v1.0/companies/{company_id}/accounting/ar/collections/portal_accessCustomer portal billing links
  11. POST /rest/v1.0/companies/{company_id}/accounting/ar/collections/portal_accessLink a customer portal grant to an AR customer (arApprove)
  12. POST /rest/v1.0/companies/{company_id}/accounting/ar/collections/portal_access/{id}/revokeRevoke a billing link (arApprove)
  13. GET /rest/v1.0/companies/{company_id}/accounting/ar/collections/promisesPromises to pay
  14. POST /rest/v1.0/companies/{company_id}/accounting/ar/collections/promisesRecord a promise to pay (arEnter)
  15. POST /rest/v1.0/companies/{company_id}/accounting/ar/collections/promises/{id}/cancelCancel an open promise (arEnter)
  16. POST /rest/v1.0/companies/{company_id}/accounting/ar/collections/runRun collections now (arEnter)
  17. GET /rest/v1.0/companies/{company_id}/accounting/ar/collections/settingsCollections and online payment settings
  18. PATCH /rest/v1.0/companies/{company_id}/accounting/ar/collections/settingsUpdate collections settings (arApprove)
  19. GET /rest/v1.0/companies/{company_id}/accounting/ar/collections/worklistPrioritized collections worklist
  20. GET /rest/v1.0/companies/{company_id}/accounting/ar/customersList AR customers
  21. GET /rest/v1.0/companies/{company_id}/accounting/ar/customers/{id}Customer open balances net of posted receipts and reversals; paginated invoice history
  22. GET /rest/v1.0/companies/{company_id}/accounting/ar/customers/{id}/collection_notesLatest 100 collection notes for the customer in permitted entities.
  23. POST /rest/v1.0/companies/{company_id}/accounting/ar/customers/{id}/collection_notesAdd a collection note (optional invoice and promise to pay). arEnter.
  24. GET /rest/v1.0/companies/{company_id}/accounting/ar/customers/{id}/collectionsA customer's collections view
  25. PATCH /rest/v1.0/companies/{company_id}/accounting/ar/customers/{id}/collectionsUpdate a customer's collections profile (arEnter)
  26. GET /rest/v1.0/companies/{company_id}/accounting/ar/customers/{id}/statementCustomer statement: open posted invoices, unapplied cash and balance due, with the billing contact.
  27. POST /rest/v1.0/companies/{company_id}/accounting/ar/depositsDeposit posted receipts held in UNDEPOSITED_FUNDS to a bank account as one journal (Dr bank / Cr undeposited funds). arApprove; idempotent by request_key.
  28. GET /rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}Get a GMP application
  29. PATCH /rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}Edit a GMP application
  30. POST /rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/billBill a GMP application
  31. POST /rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/certifyCertify a GMP application
  32. GET /rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/packageGMP application owner package
  33. GET /rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/registerGMP application cost register
  34. POST /rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/returnReturn a GMP application
  35. POST /rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/submitSubmit a GMP application
  36. POST /rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/voidVoid a GMP application
  37. POST /rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/withdrawWithdraw a GMP certification
  38. POST /rest/v1.0/companies/{company_id}/accounting/ar/gmp_draws/{id}/decisionDecide a GMP draw
  39. GET /rest/v1.0/companies/{company_id}/accounting/ar/gmp/statusGMP status of a project
  40. GET /rest/v1.0/companies/{company_id}/accounting/ar/invoicesList scoped invoices (default 100, maximum 100 per page)
  41. POST /rest/v1.0/companies/{company_id}/accounting/ar/invoicesCreate a draft; a retry with the same request key and payload returns the original invoice
  42. GET /rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}Get scoped invoice
  43. PATCH /rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}Replace current draft revision; all editors are excluded from approval
  44. GET /rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/attachmentsList attachments on a AR invoice
  45. POST /rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/attachmentsAttach a file to a AR invoice
  46. POST /rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/credit_applicationsApply a posted on-account credit memo to open invoice lines (Dr AR control / Cr receivable line). arApprove; idempotent by request_key.
  47. POST /rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/disputeFlag or clear a collections dispute on a posted invoice. Disputed invoices age in the Disputed column. arEnter.
  48. GET /rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/pdfInvoice PDF
  49. POST /rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/reverseAppend a source-owned reversal. Independent arApprove required. Identical retries return the original reversal.
  50. POST /rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/sendQueue a posted invoice for email to the customer's billing contact, with the invoice PDF attached.
  51. POST /rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/transitionSubmit, return to draft, independently approve, or post an invoice
  52. POST /rest/v1.0/companies/{company_id}/accounting/ar/invoices/from_billingDraft an AR invoice from a non-progress billing
  53. POST /rest/v1.0/companies/{company_id}/accounting/ar/invoices/from_payment_applicationBill a certified owner pay app in AR (once per pay app)
  54. GET /rest/v1.0/companies/{company_id}/accounting/ar/payment_applications/{id}/pdfG702/G703 PDF of a certified owner pay app
  55. PUT /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/billing_methodSet a prime contract's billing method
  56. GET /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/billing_termsGet a prime contract's billing terms
  57. PUT /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/billing_termsPropose a prime contract's billing terms
  58. POST /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/billing_terms/approveApprove a prime contract's proposed billing terms
  59. GET /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/closeoutGet a prime contract's closeout documents
  60. PUT /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/closeoutSet a prime contract's closeout documents
  61. GET /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/gmp_applicationsList a GMP contract's applications
  62. POST /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/gmp_applicationsStart a GMP application
  63. GET /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/gmp_closeoutGMP close-out reconciliation
  64. GET /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/gmp_drawsList GMP contingency and allowance draws
  65. POST /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/gmp_drawsPropose a GMP contingency or allowance draw
  66. GET /rest/v1.0/companies/{company_id}/accounting/ar/receiptsReceipt history, 50 per page
  67. POST /rest/v1.0/companies/{company_id}/accounting/ar/receiptsRecord a fully allocated draft; matching request-key retries return the original receipt
  68. GET /rest/v1.0/companies/{company_id}/accounting/ar/receipts/{id}Receipt detail and immutable applications
  69. POST /rest/v1.0/companies/{company_id}/accounting/ar/receipts/{id}/applicationsApply a posted receipt's unapplied cash to open invoice lines, or transfer its allocations between lines. arApprove; idempotent by request_key.
  70. GET /rest/v1.0/companies/{company_id}/accounting/ar/receipts/{id}/attachmentsList attachments on a AR receipt
  71. POST /rest/v1.0/companies/{company_id}/accounting/ar/receipts/{id}/attachmentsAttach a file to a AR receipt
  72. POST /rest/v1.0/companies/{company_id}/accounting/ar/receipts/{id}/reverseAppend a source-owned reversal. Independent arApprove required. Identical retries return the original reversal.
  73. POST /rest/v1.0/companies/{company_id}/accounting/ar/receipts/{id}/transitionIndependently approve or post; balances are revalidated under the company lock
  74. GET /rest/v1.0/companies/{company_id}/accounting/ar/receipts/open_itemsOpen original AR distributions for one customer/entity; pages over open invoices only, oldest due first
  75. GET /rest/v1.0/companies/{company_id}/accounting/ar/refundsCustomer refunds, newest first (paginated).
  76. POST /rest/v1.0/companies/{company_id}/accounting/ar/refundsDraft a refund of customer credit: a posted receipt's unapplied cash or an on-account credit memo. arEnter; idempotent by request_key.
  77. GET /rest/v1.0/companies/{company_id}/accounting/ar/refunds/{id}Refund detail.
  78. POST /rest/v1.0/companies/{company_id}/accounting/ar/refunds/{id}/transitionPost, cancel or reverse a customer refund.

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/collections/disputes

Disputes

Disputes in permitted entities, newest first; filter by status and customer_id. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • status
    stringquery
    One of: open, resolved, withdrawn.
  • customer_id
    integerquery
  • page
    integerquery
  • per_page
    integerquery

Response · 200 · object[]

  • id
    integerrequired
  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • invoice_id
    integerrequired
  • reason_code
    stringrequired
    One of: pricing, quantity, quality, not_received, duplicate, retainage, change_order, documentation, other.
  • amount
    stringrequired
  • description
    string | nullrequired
  • status
    stringrequired
    One of: open, resolved, withdrawn.
  • source
    stringrequired
    One of: staff, portal.
  • raised_by_id
    integer | nullrequired
  • resolution
    string | nullrequired
  • resolved_by_id
    integer | nullrequired
  • resolved_at
    string (date-time) | nullrequired
  • created_at
    string (date-time)required
  • days_open
    integer | nullrequired

Errors

  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 422Invalid query parameter

Example request

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

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/collections/disputes

Open a dispute on a posted invoice (arEnter)

Reason code and amount disputed (open disputes cannot exceed the invoice total). Flags the invoice disputed: aging shows it in the Disputed column and dunning and finance charges skip it. Idempotent on request_key. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • 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

  • request_key
    string (uuid)required
  • dispute
    objectrequired
  • dispute.invoice_id
    integerrequired
  • dispute.reason_code
    stringrequired
    One of: pricing, quantity, quality, not_received, duplicate, retainage, change_order, documentation, other.
  • dispute.amount
    stringrequired
  • dispute.description
    string | null

Response · 201 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • invoice_id
    integerrequired
  • reason_code
    stringrequired
    One of: pricing, quantity, quality, not_received, duplicate, retainage, change_order, documentation, other.
  • amount
    stringrequired
  • description
    string | nullrequired
  • status
    stringrequired
    One of: open, resolved, withdrawn.
  • source
    stringrequired
    One of: staff, portal.
  • raised_by_id
    integer | nullrequired
  • resolution
    string | nullrequired
  • resolved_by_id
    integer | nullrequired
  • resolved_at
    string (date-time) | nullrequired
  • created_at
    string (date-time)required
  • days_open
    integer | nullrequired

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 409Conflict (state changed, duplicate or request key reuse)
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/collections/disputes" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "request_key": "00000000-0000-4000-8000-000000000000",
  "dispute": {
    "invoice_id": 1,
    "reason_code": "pricing",
    "amount": "0.00"
  }
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/collections/disputes/{id}

A dispute

One dispute in permitted entities. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • invoice_id
    integerrequired
  • reason_code
    stringrequired
    One of: pricing, quantity, quality, not_received, duplicate, retainage, change_order, documentation, other.
  • amount
    stringrequired
  • description
    string | nullrequired
  • status
    stringrequired
    One of: open, resolved, withdrawn.
  • source
    stringrequired
    One of: staff, portal.
  • raised_by_id
    integer | nullrequired
  • resolution
    string | nullrequired
  • resolved_by_id
    integer | nullrequired
  • resolved_at
    string (date-time) | nullrequired
  • created_at
    string (date-time)required
  • days_open
    integer | nullrequired

Errors

  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 422Invalid query parameter

Example request

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

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/collections/disputes/{id}/resolve

Resolve or withdraw a dispute (arEnter)

Closing the last open dispute on an invoice clears its disputed flag. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • action
    stringrequired
    One of: resolve, withdraw.
  • resolution
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • invoice_id
    integerrequired
  • reason_code
    stringrequired
    One of: pricing, quantity, quality, not_received, duplicate, retainage, change_order, documentation, other.
  • amount
    stringrequired
  • description
    string | nullrequired
  • status
    stringrequired
    One of: open, resolved, withdrawn.
  • source
    stringrequired
    One of: staff, portal.
  • raised_by_id
    integer | nullrequired
  • resolution
    string | nullrequired
  • resolved_by_id
    integer | nullrequired
  • resolved_at
    string (date-time) | nullrequired
  • created_at
    string (date-time)required
  • days_open
    integer | nullrequired

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 409Conflict (state changed, duplicate or request key reuse)
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/collections/disputes/1/resolve" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "action": "resolve",
  "resolution": "string"
}'

Accounting / Accounts Receivable

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

Online payments

Customer portal payments in permitted entities: pending until the provider confirms, then succeeded (receipt posted to the clearing account), failed, or settled at payout; held (nothing posted, the reason in failure_reason) when the provider's captured or paid-out figures, or the pending receipt's state, disagree with the books. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • status
    stringquery
    One of: pending, succeeded, failed, settled, held.
  • page
    integerquery
  • per_page
    integerquery

Response · 200 · object[]

  • id
    integerrequired
  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • provider
    stringrequired
  • provider_ref
    stringrequired
  • method
    stringrequired
    One of: ach, card.
  • currency
    stringrequired
  • amount
    stringrequired
  • surcharge
    stringrequired
  • convenience_fee
    stringrequired
  • total_charged
    stringrequired
  • processor_fee
    stringrequired
  • status
    stringrequired
    One of: pending, succeeded, failed, settled, held.
  • receipt_id
    integer | nullrequired
  • payout_id
    integer | nullrequired
  • failure_reason
    string | nullrequired
  • invoice_ids
    integer[]required
  • confirmed_at
    string (date-time) | nullrequired
  • settled_at
    string (date-time) | nullrequired
  • created_at
    string (date-time)required

Errors

  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 422Invalid query parameter

Example request

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

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/collections/payments/{id}

An online payment

One customer portal payment in permitted entities. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • provider
    stringrequired
  • provider_ref
    stringrequired
  • method
    stringrequired
    One of: ach, card.
  • currency
    stringrequired
  • amount
    stringrequired
  • surcharge
    stringrequired
  • convenience_fee
    stringrequired
  • total_charged
    stringrequired
  • processor_fee
    stringrequired
  • status
    stringrequired
    One of: pending, succeeded, failed, settled, held.
  • receipt_id
    integer | nullrequired
  • payout_id
    integer | nullrequired
  • failure_reason
    string | nullrequired
  • invoice_ids
    integer[]required
  • confirmed_at
    string (date-time) | nullrequired
  • settled_at
    string (date-time) | nullrequired
  • created_at
    string (date-time)required

Errors

  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 422Invalid query parameter

Example request

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

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/collections/policies

Dunning policies

One reminder cadence per customer class, with steps relative to the due date. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • page
    integerquery
  • per_page
    integerquery

Response · 200 · object[]

  • id
    integerrequired
  • customer_class
    stringrequired
  • name
    stringrequired
  • is_active
    booleanrequired
  • escalation_user_id
    integer | nullrequired
  • revision
    integerrequired
  • steps
    object[]required
  • steps[].id
    integerrequired
  • steps[].offset_days
    integerrequired
  • steps[].channel
    stringrequired
  • steps[].subject
    stringrequired
  • steps[].body
    stringrequired
  • steps[].escalate
    booleanrequired
  • steps[].is_active
    booleanrequired

Errors

  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 422Invalid query parameter

Example request

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

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/collections/policies

Create a dunning policy (arApprove)

One policy per customer class (409 otherwise). Steps: offset days relative to the due date (rolled forward to a business day), email subject and body templates ({{invoice_number}}, {{due_date}}, {{open_amount}}, {{days_past_due}}, {{customer_name}}, {{company_name}}), and escalation to the internal owner. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • 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

  • policy
    objectrequired
  • policy.customer_class
    stringrequired
  • policy.name
    stringrequired
  • policy.is_active
    boolean
  • policy.escalation_user_id
    integer | null
  • policy.steps
    object[]required
  • policy.steps[].offset_days
    integerrequired
  • policy.steps[].subject
    stringrequired
  • policy.steps[].body
    stringrequired
  • policy.steps[].escalate
    boolean
  • policy.steps[].channel
    string

Response · 201 · object

  • id
    integerrequired
  • customer_class
    stringrequired
  • name
    stringrequired
  • is_active
    booleanrequired
  • escalation_user_id
    integer | nullrequired
  • revision
    integerrequired
  • steps
    object[]required
  • steps[].id
    integerrequired
  • steps[].offset_days
    integerrequired
  • steps[].channel
    stringrequired
  • steps[].subject
    stringrequired
  • steps[].body
    stringrequired
  • steps[].escalate
    booleanrequired
  • steps[].is_active
    booleanrequired

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 409Conflict (state changed, duplicate or request key reuse)
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/collections/policies" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "policy": {
    "customer_class": "string",
    "name": "string",
    "steps": [
      {
        "offset_days": 1,
        "subject": "string",
        "body": "string"
      }
    ]
  }
}'

Accounting / Accounts Receivable

PATCH /rest/v1.0/companies/{company_id}/accounting/ar/collections/policies/{id}

Replace a dunning policy's cadence (arApprove)

Steps keep their identity by offset, so a re-saved step never re-sends; dropped offsets are deactivated. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • policy
    objectrequired
  • policy.customer_class
    stringrequired
  • policy.name
    stringrequired
  • policy.is_active
    boolean
  • policy.escalation_user_id
    integer | null
  • policy.steps
    object[]required
  • policy.steps[].offset_days
    integerrequired
  • policy.steps[].subject
    stringrequired
  • policy.steps[].body
    stringrequired
  • policy.steps[].escalate
    boolean
  • policy.steps[].channel
    string

Response · 200 · object

  • id
    integerrequired
  • customer_class
    stringrequired
  • name
    stringrequired
  • is_active
    booleanrequired
  • escalation_user_id
    integer | nullrequired
  • revision
    integerrequired
  • steps
    object[]required
  • steps[].id
    integerrequired
  • steps[].offset_days
    integerrequired
  • steps[].channel
    stringrequired
  • steps[].subject
    stringrequired
  • steps[].body
    stringrequired
  • steps[].escalate
    booleanrequired
  • steps[].is_active
    booleanrequired

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 409Conflict (state changed, duplicate or request key reuse)
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/collections/policies/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "policy": {
    "customer_class": "string",
    "name": "string",
    "steps": [
      {
        "offset_days": 1,
        "subject": "string",
        "body": "string"
      }
    ]
  }
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/collections/portal_access

Customer portal billing links

Links from customer portal grants to AR customers. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • customer_id
    integerquery
  • page
    integerquery
  • per_page
    integerquery

Response · 200 · object[]

  • id
    integerrequired
  • grant_id
    integerrequired
  • customer_id
    integerrequired
  • allow_payments
    booleanrequired
  • active
    booleanrequired
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • revoked_at
    string (date-time) | nullrequired
  • revoked_by_id
    integer | nullrequired

Errors

  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 422Invalid query parameter

Example request

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

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/collections/portal_access

Link a customer portal grant to an AR customer (arApprove)

The grant's principal then sees that customer's posted invoices on the grant's project, and may pay online when allow_payments is true. Needs a grant over every entity. One active link per grant. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • 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

  • request_key
    string (uuid)
  • portal_access
    objectrequired
  • portal_access.grant_id
    integerrequired
  • portal_access.customer_id
    integerrequired
  • portal_access.allow_payments
    boolean

Response · 201 · object

  • id
    integerrequired
  • grant_id
    integerrequired
  • customer_id
    integerrequired
  • allow_payments
    booleanrequired
  • active
    booleanrequired
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • revoked_at
    string (date-time) | nullrequired
  • revoked_by_id
    integer | nullrequired

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 409Conflict (state changed, duplicate or request key reuse)
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/collections/portal_access" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "portal_access": {
    "grant_id": 1,
    "customer_id": 1
  }
}'

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/collections/portal_access/{id}/revoke

Revoke a billing link (arApprove)

The portal stops showing billing for the grant at once. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • grant_id
    integerrequired
  • customer_id
    integerrequired
  • allow_payments
    booleanrequired
  • active
    booleanrequired
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • revoked_at
    string (date-time) | nullrequired
  • revoked_by_id
    integer | nullrequired

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 409Conflict (state changed, duplicate or request key reuse)
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/collections/portal_access/1/revoke" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "reason": "string"
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/collections/promises

Promises to pay

Promises in permitted entities; status kept or broken is recorded by the daily collections job from posted receipts. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • status
    stringquery
    One of: open, kept, broken, cancelled.
  • customer_id
    integerquery
  • page
    integerquery
  • per_page
    integerquery

Response · 200 · object[]

  • id
    integerrequired
  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • invoice_ids
    integer[]required
  • start_date
    string (date)required
  • promised_date
    string (date)required
  • amount
    stringrequired
  • received_amount
    stringrequired
  • status
    stringrequired
    One of: open, kept, broken, cancelled.
  • source
    stringrequired
    One of: staff, portal.
  • note
    string | nullrequired
  • created_by_id
    integer | nullrequired
  • resolved_date
    string (date) | nullrequired
  • created_at
    string (date-time)required

Errors

  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 422Invalid query parameter

Example request

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

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/collections/promises

Record a promise to pay (arEnter)

Date and amount, optionally for named invoices. While open it pauses dunning for those invoices (or the customer). Idempotent on request_key. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • 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

  • request_key
    string (uuid)required
  • promise
    objectrequired
  • promise.entity_id
    integerrequired
  • promise.customer_id
    integerrequired
  • promise.invoice_ids
    integer[]
  • promise.promised_date
    string (date)required
  • promise.amount
    stringrequired
  • promise.note
    string | null

Response · 201 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • invoice_ids
    integer[]required
  • start_date
    string (date)required
  • promised_date
    string (date)required
  • amount
    stringrequired
  • received_amount
    stringrequired
  • status
    stringrequired
    One of: open, kept, broken, cancelled.
  • source
    stringrequired
    One of: staff, portal.
  • note
    string | nullrequired
  • created_by_id
    integer | nullrequired
  • resolved_date
    string (date) | nullrequired
  • created_at
    string (date-time)required

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 409Conflict (state changed, duplicate or request key reuse)
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/collections/promises" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "request_key": "00000000-0000-4000-8000-000000000000",
  "promise": {
    "entity_id": 1,
    "customer_id": 1,
    "promised_date": "2026-11-01",
    "amount": "0.00"
  }
}'

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/collections/promises/{id}/cancel

Cancel an open promise (arEnter)

A cancelled promise no longer pauses dunning and is left out of the kept rate. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • invoice_ids
    integer[]required
  • start_date
    string (date)required
  • promised_date
    string (date)required
  • amount
    stringrequired
  • received_amount
    stringrequired
  • status
    stringrequired
    One of: open, kept, broken, cancelled.
  • source
    stringrequired
    One of: staff, portal.
  • note
    string | nullrequired
  • created_by_id
    integer | nullrequired
  • resolved_date
    string (date) | nullrequired
  • created_at
    string (date-time)required

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 409Conflict (state changed, duplicate or request key reuse)
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/collections/promises/1/cancel" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "reason": "string"
}'

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/collections/run

Run collections now (arEnter)

Records kept/broken promises and sends due dunning steps, exactly as the daily job: business days and outside quiet hours only, at most once per invoice and step. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Response · 200 · object

  • as_of
    string (date)required
  • status
    stringrequired
    One of: ran, disabled, not_business_day, quiet_hours, no_policy.
  • resume_at
    string (date-time) | nullrequired
  • sent
    integerrequired
  • skipped
    integerrequired
  • failed
    integerrequired
  • suppressed
    integerrequired
  • paused
    objectrequired
  • promises
    objectrequired
  • promises.kept
    integerrequired
  • promises.broken
    integerrequired

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 409Conflict (state changed, duplicate or request key reuse)
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/collections/run" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/collections/settings

Collections and online payment settings

Dunning calendar (quiet hours, business days, holidays), promise grace days and the online payment setup (provider, clearing, payout and fee accounts; surcharge and convenience fee, both off by default). Any AR reader. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Response · 200 · object

  • revision
    integerrequired
  • dunning_enabled
    booleanrequired
  • quiet_start
    stringrequired
  • quiet_end
    stringrequired
  • business_days
    integer[]required
  • holidays
    string (date)[]required
  • promise_grace_days
    integerrequired
  • portal_payments_enabled
    booleanrequired
  • provider
    stringrequired
  • ach_enabled
    booleanrequired
  • card_enabled
    booleanrequired
  • clearing_account_id
    integer | nullrequired
  • payout_account_id
    integer | nullrequired
  • fee_account_id
    integer | nullrequired
  • surcharge_enabled
    booleanrequired
  • surcharge_pct
    stringrequired
  • convenience_fee_enabled
    booleanrequired
  • convenience_fee
    stringrequired
  • fee_income_account_id
    integer | nullrequired

Errors

  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 422Invalid query parameter

Example request

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

Accounting / Accounts Receivable

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

Update collections settings (arApprove)

Partial update. Online payments need clearing, payout and processor fee accounts; surcharges and convenience fees need a fee income account (their legality varies by jurisdiction and card network). revision guards concurrent edits (409). Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Request body

  • revision
    integer
  • settings
    objectrequired
  • settings.dunning_enabled
    boolean
  • settings.quiet_start
    string
  • settings.quiet_end
    string
  • settings.business_days
    integer[]
  • settings.holidays
    string (date)[]
  • settings.promise_grace_days
    integer
  • settings.portal_payments_enabled
    boolean
  • settings.ach_enabled
    boolean
  • settings.card_enabled
    boolean
  • settings.clearing_account_id
    integer | null
  • settings.payout_account_id
    integer | null
  • settings.fee_account_id
    integer | null
  • settings.surcharge_enabled
    boolean
  • settings.surcharge_pct
    string
  • settings.convenience_fee_enabled
    boolean
  • settings.convenience_fee
    string
  • settings.fee_income_account_id
    integer | null

Response · 200 · object

  • revision
    integerrequired
  • dunning_enabled
    booleanrequired
  • quiet_start
    stringrequired
  • quiet_end
    stringrequired
  • business_days
    integer[]required
  • holidays
    string (date)[]required
  • promise_grace_days
    integerrequired
  • portal_payments_enabled
    booleanrequired
  • provider
    stringrequired
  • ach_enabled
    booleanrequired
  • card_enabled
    booleanrequired
  • clearing_account_id
    integer | nullrequired
  • payout_account_id
    integer | nullrequired
  • fee_account_id
    integer | nullrequired
  • surcharge_enabled
    booleanrequired
  • surcharge_pct
    stringrequired
  • convenience_fee_enabled
    booleanrequired
  • convenience_fee
    stringrequired
  • fee_income_account_id
    integer | nullrequired

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 409Conflict (state changed, duplicate or request key reuse)
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/collections/settings" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "settings": {}
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/collections/worklist

Prioritized collections worklist

Customers with open current AR in permitted entities, ordered by score = Σ open × age weight × risk (deterministic; docs/accounting/COLLECTIONS-PORTAL.md). Disputed invoices are excluded from the score and shown separately. Paginated. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • as_of
    string (date)query
  • collector_id
    integerquery
  • entity_id
    integerquery
  • page
    integerquery
  • per_page
    integerquery

Response · 200 · object[]

  • customer_id
    integerrequired
  • customer_name
    stringrequired
  • customer_class
    stringrequired
  • collector_user_id
    integer | nullrequired
  • on_hold
    booleanrequired
  • follow_up_date
    string (date) | nullrequired
  • open_current
    stringrequired
  • past_due
    stringrequired
  • oldest_days_past_due
    integerrequired
  • disputed_amount
    stringrequired
  • open_disputes
    integerrequired
  • open_promise
    object | nullrequired
  • open_promise.id
    integerrequired
  • open_promise.promised_date
    string (date)required
  • open_promise.amount
    stringrequired
  • broken_promises
    integerrequired
  • days_to_pay
    string | nullrequired
  • terms_days
    integerrequired
  • score
    stringrequired
  • risk
    stringrequired
  • last_activity_at
    string (date-time) | nullrequired

Errors

  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 422Invalid query parameter

Example request

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

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/customers

List AR customers

Active parties usable as AR customers (no accounting profile, or a profile marked customer), ordered by name. Paginated with Total and Link headers. Party names only; billing activity stays behind the entity-scoped customer detail. Refused (403) to project-scoped grants. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • search
    stringquery
  • page
    integerquery
  • per_page
    integerquery

Response · 200 · object[]

  • id
    integerrequired
  • name
    stringrequired
  • has_profile
    booleanrequired
  • term_id
    integer | nullrequired

Errors

  • 401Authentication required
  • 403Tenant, permission or entity access denied

Example request

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

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/customers/{id}

Customer open balances net of posted receipts and reversals; paginated invoice history

Returns customer billing information scoped to the company and permitted invoice entities. This is current workflow information, not an as-of AR control reconciliation. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • page
    integerquery

Response · 200 · object

  • customer
    objectrequired
  • customer.id
    integerrequired
  • customer.name
    stringrequired
  • balances
    object[]required
  • balances[].currency
    stringrequired
  • balances[].current
    stringrequired
  • balances[].retainage
    stringrequired
  • total
    integerrequired
  • invoices
    object[]required
  • invoices[].entity_id
    integerrequired
  • invoices[].customer_id
    integerrequired
  • invoices[].source_reference
    stringrequired
  • invoices[].invoice_date
    string (date)required
  • invoices[].posting_date
    string (date)required
  • invoices[].due_date
    string (date)required
  • invoices[].memo
    string | nullrequired
  • invoices[].lines
    object[]required
  • invoices[].id
    integerrequired
  • invoices[].number
    stringrequired
  • invoices[].source_type
    stringrequired
  • invoices[].source_id
    integerrequired
  • invoices[].source_revision
    integerrequired
  • invoices[].revision
    integerrequired
  • invoices[].status
    stringrequired
    One of: draft, pending_approval, approved, posted, reversed, cancelled.
  • invoices[].currency
    stringrequired
  • invoices[].total
    stringrequired
  • invoices[].retainage_amount
    stringrequired
  • invoices[].current_amount
    stringrequired
  • invoices[].open_current
    stringrequired
  • invoices[].open_retainage
    stringrequired
  • invoices[].prepared_by_id
    integerrequired
  • invoices[].approved_by_id
    integer | nullrequired
  • invoices[].approved_at
    string (date-time) | nullrequired
  • invoices[].journal_entry_id
    integer | nullrequired
  • invoices[].paid_current
    stringrequired
  • invoices[].paid_retainage
    stringrequired
  • invoices[].corrects_invoice_id
    integer | nullrequired
  • invoices[].reversal
    object | nullrequired
  • invoices[].applications
    object[]required
  • invoices[].kind
    stringrequired
    One of: standard, retainage_release, credit_memo.
  • invoices[].payment_application_id
    integer | nullrequired
    Owner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
  • invoices[].prime_contract_id
    integer | nullrequired
  • invoices[].project_id
    integer | nullrequired
  • invoices[].released_retainage
    stringrequired
    Retainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
  • invoices[].tax_amount
    stringrequired
  • invoices[].disputed
    booleanrequired
  • invoices[].dispute_reason
    string | nullrequired
  • invoices[].credited_current
    stringrequired
    Current AR settled by credit memos, including any sales tax they reverse.
  • invoices[].credit_reason
    string | nullrequired
    Credit memos only. One of: return, write_off, discount, tax_adjustment, null.
  • invoices[].cancellation_reason
    string | nullrequired
  • invoices[].tax_override_reason
    string | nullrequired
  • invoices[].tax_warnings
    string[]required
    Sales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
  • invoices[].on_account_amount
    string | null
    Credit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
  • invoices[].available_credit
    string | null
    Posted, unreversed credit memos: on-account amount less applications and posted refunds.
  • invoices[].credit_applications
    object[]
    On-account credit memos applied to this invoice (while each stands).
  • invoices[].outside_contract_reason
    string | nullrequired
  • profile
    object | null
  • profile.is_customer
    boolean
  • profile.term_id
    integer | null
  • profile.term_code
    string | null
  • profile.due_days
    integer | null
  • profile.credit_limit
    string | null
  • profile.billing_contact_name
    string | null
  • profile.billing_email
    string | null
  • profile.billing_address
    string | null

Errors

  • 401Authentication required
  • 403Tenant, permission or entity access denied
  • 404Scoped record not found
  • 409State, revision, duplicate source or request conflict
  • 422Invalid input, references, configuration or posting period

Example request

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

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/customers/{id}/collection_notes

Latest 100 collection notes for the customer in permitted entities.

Newest first. Paginated (page/per_page; Total and Link headers). Latest 100 collection notes for the customer in permitted entities. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • page
    integerquery
  • per_page
    integerquery

Response · 200 · object[]

  • kind
    string
    One of: note, call, email.
  • follow_up_date
    string (date) | null
  • id
    integer
  • entity_id
    integer
  • customer_id
    integer
  • invoice_id
    integer | null
  • note
    string
  • promise_date
    string (date) | null
  • promise_amount
    string | null
  • created_by_id
    integer
  • created_at
    string (date-time)

Errors

  • 401Authentication required
  • 403Scope or separation of duties denied
  • 404Scoped source not found

Example request

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

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/customers/{id}/collection_notes

Add a collection note (optional invoice and promise to pay). arEnter.

Add a collection note (optional invoice and promise to pay). arEnter. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • 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

  • kind
    string
    One of: note, call, email.
  • follow_up_date
    string (date) | null
  • entity_id
    integerrequired
  • invoice_id
    integer | null
  • note
    stringrequired
  • promise_date
    string (date) | null
  • promise_amount
    string | null

Response · 201 · object

  • kind
    string
    One of: note, call, email.
  • follow_up_date
    string (date) | null
  • id
    integer
  • entity_id
    integer
  • customer_id
    integer
  • invoice_id
    integer | null
  • note
    string
  • promise_date
    string (date) | null
  • promise_amount
    string | null
  • created_by_id
    integer
  • created_at
    string (date-time)

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or separation of duties denied
  • 404Scoped source not found
  • 409State, revision, overapplication or idempotency conflict
  • 422Invalid data, dates, account or closed period

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/customers/1/collection_notes" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "entity_id": 1,
  "note": "string"
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/customers/{id}/collections

A customer's collections view

Profile (class, collector, hold, follow-up), days to pay (amount-weighted, last 365 days), disputes, promises (live status) and dunning history in permitted entities. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • customer
    objectrequired
  • customer.id
    integerrequired
  • customer.name
    stringrequired
  • as_of
    string (date)required
  • profile
    objectrequired
  • profile.customer_id
    integerrequired
  • profile.customer_class
    stringrequired
  • profile.collector_user_id
    integer | nullrequired
  • profile.on_hold
    booleanrequired
  • profile.hold_reason
    string | nullrequired
  • profile.follow_up_date
    string (date) | nullrequired
  • days_to_pay
    string | nullrequired
  • disputes
    object[]required
  • disputes[].id
    integerrequired
  • disputes[].entity_id
    integerrequired
  • disputes[].customer_id
    integerrequired
  • disputes[].invoice_id
    integerrequired
  • disputes[].reason_code
    stringrequired
    One of: pricing, quantity, quality, not_received, duplicate, retainage, change_order, documentation, other.
  • disputes[].amount
    stringrequired
  • disputes[].description
    string | nullrequired
  • disputes[].status
    stringrequired
    One of: open, resolved, withdrawn.
  • disputes[].source
    stringrequired
    One of: staff, portal.
  • disputes[].raised_by_id
    integer | nullrequired
  • disputes[].resolution
    string | nullrequired
  • disputes[].resolved_by_id
    integer | nullrequired
  • disputes[].resolved_at
    string (date-time) | nullrequired
  • disputes[].created_at
    string (date-time)required
  • disputes[].days_open
    integer | nullrequired
  • promises
    object[]required
  • promises[].id
    integerrequired
  • promises[].entity_id
    integerrequired
  • promises[].customer_id
    integerrequired
  • promises[].invoice_ids
    integer[]required
  • promises[].start_date
    string (date)required
  • promises[].promised_date
    string (date)required
  • promises[].amount
    stringrequired
  • promises[].received_amount
    stringrequired
  • promises[].status
    stringrequired
    One of: open, kept, broken, cancelled.
  • promises[].source
    stringrequired
    One of: staff, portal.
  • promises[].note
    string | nullrequired
  • promises[].created_by_id
    integer | nullrequired
  • promises[].resolved_date
    string (date) | nullrequired
  • promises[].created_at
    string (date-time)required
  • dunning_sends
    object[]required
  • dunning_sends[].id
    integerrequired
  • dunning_sends[].entity_id
    integerrequired
  • dunning_sends[].customer_id
    integerrequired
  • dunning_sends[].invoice_id
    integerrequired
  • dunning_sends[].step_id
    integerrequired
  • dunning_sends[].offset_days
    integerrequired
  • dunning_sends[].scheduled_date
    string (date)required
  • dunning_sends[].run_date
    string (date)required
  • dunning_sends[].status
    stringrequired
    One of: sent, skipped, failed.
  • dunning_sends[].reason
    string | nullrequired
  • dunning_sends[].escalated_to_user_id
    integer | nullrequired
  • dunning_sends[].created_at
    string (date-time)required

Errors

  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 422Invalid query parameter

Example request

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

Accounting / Accounts Receivable

PATCH /rest/v1.0/companies/{company_id}/accounting/ar/customers/{id}/collections

Update a customer's collections profile (arEnter)

Customer class (selects the dunning policy), collector assignment, hold (pauses dunning; needs a reason) and follow-up date. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • profile
    objectrequired
  • profile.customer_class
    string
  • profile.collector_user_id
    integer | null
  • profile.on_hold
    boolean
  • profile.hold_reason
    string | null
  • profile.follow_up_date
    string (date) | null

Response · 200 · object

  • customer
    objectrequired
  • customer.id
    integerrequired
  • customer.name
    stringrequired
  • as_of
    string (date)required
  • profile
    objectrequired
  • profile.customer_id
    integerrequired
  • profile.customer_class
    stringrequired
  • profile.collector_user_id
    integer | nullrequired
  • profile.on_hold
    booleanrequired
  • profile.hold_reason
    string | nullrequired
  • profile.follow_up_date
    string (date) | nullrequired
  • days_to_pay
    string | nullrequired
  • disputes
    object[]required
  • disputes[].id
    integerrequired
  • disputes[].entity_id
    integerrequired
  • disputes[].customer_id
    integerrequired
  • disputes[].invoice_id
    integerrequired
  • disputes[].reason_code
    stringrequired
    One of: pricing, quantity, quality, not_received, duplicate, retainage, change_order, documentation, other.
  • disputes[].amount
    stringrequired
  • disputes[].description
    string | nullrequired
  • disputes[].status
    stringrequired
    One of: open, resolved, withdrawn.
  • disputes[].source
    stringrequired
    One of: staff, portal.
  • disputes[].raised_by_id
    integer | nullrequired
  • disputes[].resolution
    string | nullrequired
  • disputes[].resolved_by_id
    integer | nullrequired
  • disputes[].resolved_at
    string (date-time) | nullrequired
  • disputes[].created_at
    string (date-time)required
  • disputes[].days_open
    integer | nullrequired
  • promises
    object[]required
  • promises[].id
    integerrequired
  • promises[].entity_id
    integerrequired
  • promises[].customer_id
    integerrequired
  • promises[].invoice_ids
    integer[]required
  • promises[].start_date
    string (date)required
  • promises[].promised_date
    string (date)required
  • promises[].amount
    stringrequired
  • promises[].received_amount
    stringrequired
  • promises[].status
    stringrequired
    One of: open, kept, broken, cancelled.
  • promises[].source
    stringrequired
    One of: staff, portal.
  • promises[].note
    string | nullrequired
  • promises[].created_by_id
    integer | nullrequired
  • promises[].resolved_date
    string (date) | nullrequired
  • promises[].created_at
    string (date-time)required
  • dunning_sends
    object[]required
  • dunning_sends[].id
    integerrequired
  • dunning_sends[].entity_id
    integerrequired
  • dunning_sends[].customer_id
    integerrequired
  • dunning_sends[].invoice_id
    integerrequired
  • dunning_sends[].step_id
    integerrequired
  • dunning_sends[].offset_days
    integerrequired
  • dunning_sends[].scheduled_date
    string (date)required
  • dunning_sends[].run_date
    string (date)required
  • dunning_sends[].status
    stringrequired
    One of: sent, skipped, failed.
  • dunning_sends[].reason
    string | nullrequired
  • dunning_sends[].escalated_to_user_id
    integer | nullrequired
  • dunning_sends[].created_at
    string (date-time)required

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or permission denied
  • 404Not found in the caller's scope
  • 409Conflict (state changed, duplicate or request key reuse)
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/customers/1/collections" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "profile": {}
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/customers/{id}/statement

Customer statement: open posted invoices, unapplied cash and balance due, with the billing contact.

Customer statement: open posted invoices, unapplied cash and balance due, with the billing contact. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • as_of
    string (date)query
    Statement date (default today): as-of open amounts, receipts and applications dated on or before it.

Response · 200 · object

  • customer
    object
  • customer.id
    integerrequired
  • customer.name
    stringrequired
  • profile
    object | null
    Null for an entity-restricted grant whose entities have no AR activity with the customer.
  • profile.is_customer
    boolean
  • profile.term_id
    integer | null
  • profile.term_code
    string | null
  • profile.due_days
    integer | null
  • profile.credit_limit
    string | null
  • profile.billing_contact_name
    string | null
  • profile.billing_email
    string | null
  • profile.billing_address
    string | null
  • as_of
    string (date)
  • invoices
    object[]
  • invoices[].entity_id
    integerrequired
  • invoices[].customer_id
    integerrequired
  • invoices[].source_reference
    stringrequired
  • invoices[].invoice_date
    string (date)required
  • invoices[].posting_date
    string (date)required
  • invoices[].due_date
    string (date)required
  • invoices[].memo
    string | nullrequired
  • invoices[].lines
    object[]required
  • invoices[].id
    integerrequired
  • invoices[].number
    stringrequired
  • invoices[].source_type
    stringrequired
  • invoices[].source_id
    integerrequired
  • invoices[].source_revision
    integerrequired
  • invoices[].revision
    integerrequired
  • invoices[].status
    stringrequired
    One of: draft, pending_approval, approved, posted, reversed, cancelled.
  • invoices[].currency
    stringrequired
  • invoices[].total
    stringrequired
  • invoices[].retainage_amount
    stringrequired
  • invoices[].current_amount
    stringrequired
  • invoices[].open_current
    stringrequired
  • invoices[].open_retainage
    stringrequired
  • invoices[].prepared_by_id
    integerrequired
  • invoices[].approved_by_id
    integer | nullrequired
  • invoices[].approved_at
    string (date-time) | nullrequired
  • invoices[].journal_entry_id
    integer | nullrequired
  • invoices[].paid_current
    stringrequired
  • invoices[].paid_retainage
    stringrequired
  • invoices[].corrects_invoice_id
    integer | nullrequired
  • invoices[].reversal
    object | nullrequired
  • invoices[].applications
    object[]required
  • invoices[].kind
    stringrequired
    One of: standard, retainage_release, credit_memo.
  • invoices[].payment_application_id
    integer | nullrequired
    Owner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
  • invoices[].prime_contract_id
    integer | nullrequired
  • invoices[].project_id
    integer | nullrequired
  • invoices[].released_retainage
    stringrequired
    Retainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
  • invoices[].tax_amount
    stringrequired
  • invoices[].disputed
    booleanrequired
  • invoices[].dispute_reason
    string | nullrequired
  • invoices[].credited_current
    stringrequired
    Current AR settled by credit memos, including any sales tax they reverse.
  • invoices[].credit_reason
    string | nullrequired
    Credit memos only. One of: return, write_off, discount, tax_adjustment, null.
  • invoices[].cancellation_reason
    string | nullrequired
  • invoices[].tax_override_reason
    string | nullrequired
  • invoices[].tax_warnings
    string[]required
    Sales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
  • invoices[].on_account_amount
    string | null
    Credit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
  • invoices[].available_credit
    string | null
    Posted, unreversed credit memos: on-account amount less applications and posted refunds.
  • invoices[].credit_applications
    object[]
    On-account credit memos applied to this invoice (while each stands).
  • invoices[].outside_contract_reason
    string | nullrequired
  • open_total
    string
    open_current plus retainage_not_due.
  • unapplied_cash
    string
  • balance_due
    string
    open_current less unapplied cash; unreleased retainage is not due.
  • open_current
    string
    Open current AR as of the date, net of owner-direct payment credits.
  • retainage_not_due
    string
    Unreleased retainage held as of the date; shown, not due.
  • owner_direct_credits
    string
    Owner-direct AP payments credited to this customer's AR, included in open_current.
  • on_account_credits
    string
    Open on-account credit memos as of the date (positive), netted in open_current.

Errors

  • 401Authentication required
  • 403Scope or separation of duties denied
  • 404Scoped source not found

Example request

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

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/deposits

Deposit posted receipts held in UNDEPOSITED_FUNDS to a bank account as one journal (Dr bank / Cr undeposited funds). arApprove; idempotent by request_key.

Deposit posted receipts held in UNDEPOSITED_FUNDS to a bank account as one journal (Dr bank / Cr undeposited funds). arApprove; idempotent by request_key. A preparer or contributor of any deposited receipt cannot make the deposit (403, segregation of duties). Requires the accounting:write scope.

v1.0Implemented

Parameters

  • 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

  • request_key
    string (uuid)required
  • entity_id
    integerrequired
  • bank_account_id
    integerrequired
  • posting_date
    string (date)required
  • receipt_ids
    integer[]required

Response · 201 · object

  • id
    integer
  • number
    string
  • entity_id
    integer
  • bank_account_id
    integer
  • posting_date
    string (date)
  • currency
    string
  • total
    string
  • journal_entry_id
    integer
  • receipt_ids
    integer[]

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or separation of duties denied
  • 404Scoped source not found
  • 409State, revision, overapplication or idempotency conflict
  • 422Invalid data, dates, account or closed period

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/deposits" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "request_key": "00000000-0000-4000-8000-000000000000",
  "entity_id": 1,
  "bank_account_id": 1,
  "posting_date": "2026-11-01",
  "receipt_ids": []
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}

Get a GMP application

The application with its computed result and its invoice, if billed. Refused (403) to project-scoped grants. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • prime_contract_id
    integerrequired
  • project_id
    integer
  • entity_id
    integer
  • number
    integerrequired
  • period_end
    string (date)required
  • final
    boolean
  • status
    stringrequired
    One of: draft, submitted, returned, certified, billed, void.
  • revision
    integerrequired
  • exclusions
    object
    Disallowed job cost entries: entry id -> reason.
  • stored
    object[]
  • result
    object | null
    The computed application: summary (G702-style), rows (continuation by cost code), pieces (this period's billing lines), cumulative, disallowed, nteTrims, contingency, allowances, posting (role lines), explain, warnings, errors, inputs.
  • result_hash
    string | null
  • terms_revision
    integer | null
  • earned_to_date
    string
  • retainage_to_date
    string
  • current_due
    stringrequired
  • prepared_by_id
    integer
  • contributor_ids
    integer[]
  • submitted_at
    string | null (date-time)
  • returned_at
    string | null (date-time)
  • return_reason
    string | null
  • certified_by_id
    integer | null
  • certified_at
    string | null (date-time)
  • reviewer_name
    string | null
  • reviewer_role
    string | null
  • reviewer_date
    string | null (date)
  • certification_note
    string | null
  • invoice_id
    integer | null
  • billed_at
    string | null (date-time)
  • voided_at
    string | null (date-time)
  • void_reason
    string | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

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/ar/gmp_applications/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Receivable

PATCH /rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}

Edit a GMP application

Needs ar_enter. Draft or returned applications only, at the given revision (409 when stale). exclusions replaces the disallowed job cost entries of the period (entry id -> reason); stored is the cumulative materials presently stored. An edit with only revision refreshes the application from current job cost, terms, change orders and contingency transfers. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • revision
    integerrequired
  • period_end
    string (date)
  • final
    boolean
  • exclusions
    object
  • stored
    object[]
  • stored[].cost_code_id
    integer | nullrequired
  • stored[].description
    stringrequired
  • stored[].amount
    stringrequired
  • stored[].reference
    string | null

Response · 200 · object

  • id
    integerrequired
  • prime_contract_id
    integerrequired
  • project_id
    integer
  • entity_id
    integer
  • number
    integerrequired
  • period_end
    string (date)required
  • final
    boolean
  • status
    stringrequired
    One of: draft, submitted, returned, certified, billed, void.
  • revision
    integerrequired
  • exclusions
    object
    Disallowed job cost entries: entry id -> reason.
  • stored
    object[]
  • result
    object | null
    The computed application: summary (G702-style), rows (continuation by cost code), pieces (this period's billing lines), cumulative, disallowed, nteTrims, contingency, allowances, posting (role lines), explain, warnings, errors, inputs.
  • result_hash
    string | null
  • terms_revision
    integer | null
  • earned_to_date
    string
  • retainage_to_date
    string
  • current_due
    stringrequired
  • prepared_by_id
    integer
  • contributor_ids
    integer[]
  • submitted_at
    string | null (date-time)
  • returned_at
    string | null (date-time)
  • return_reason
    string | null
  • certified_by_id
    integer | null
  • certified_at
    string | null (date-time)
  • reviewer_name
    string | null
  • reviewer_role
    string | null
  • reviewer_date
    string | null (date)
  • certification_note
    string | null
  • invoice_id
    integer | null
  • billed_at
    string | null (date-time)
  • voided_at
    string | null (date-time)
  • void_reason
    string | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

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
  • 409Stale revision, wrong state, or the sources behind the application changed
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/gmp_applications/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "revision": 1
}'

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/bill

Bill a GMP application

Needs ar_enter. Drafts the AR invoice of a certified application on the contract (customer: the contract owner; entity: the application's): one line per component billed this period (cost of the work, stored materials, general conditions, markups, fee, shared savings), or one net line when a component nets down; lines carry the job and the billing ref gmp_app:{id}; retainage is the period's retainage spread pro rata. The invoice then follows the normal submit, approve and post workflow (Dr AR, Dr retainage receivable, Cr contract revenue). 409 when already billed with a live invoice or the previous application has none. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • invoice_date
    string (date)required
  • posting_date
    string (date)
  • due_date
    string (date)
  • revenue_account_id
    integer

Response · 201 · object

  • application
    objectrequired
  • application.id
    integerrequired
  • application.prime_contract_id
    integerrequired
  • application.project_id
    integer
  • application.entity_id
    integer
  • application.number
    integerrequired
  • application.period_end
    string (date)required
  • application.final
    boolean
  • application.status
    stringrequired
    One of: draft, submitted, returned, certified, billed, void.
  • application.revision
    integerrequired
  • application.exclusions
    object
    Disallowed job cost entries: entry id -> reason.
  • application.stored
    object[]
  • application.result
    object | null
    The computed application: summary (G702-style), rows (continuation by cost code), pieces (this period's billing lines), cumulative, disallowed, nteTrims, contingency, allowances, posting (role lines), explain, warnings, errors, inputs.
  • application.result_hash
    string | null
  • application.terms_revision
    integer | null
  • application.earned_to_date
    string
  • application.retainage_to_date
    string
  • application.current_due
    stringrequired
  • application.prepared_by_id
    integer
  • application.contributor_ids
    integer[]
  • application.submitted_at
    string | null (date-time)
  • application.returned_at
    string | null (date-time)
  • application.return_reason
    string | null
  • application.certified_by_id
    integer | null
  • application.certified_at
    string | null (date-time)
  • application.reviewer_name
    string | null
  • application.reviewer_role
    string | null
  • application.reviewer_date
    string | null (date)
  • application.certification_note
    string | null
  • application.invoice_id
    integer | null
  • application.billed_at
    string | null (date-time)
  • application.voided_at
    string | null (date-time)
  • application.void_reason
    string | null
  • application.created_at
    string (date-time)
  • application.updated_at
    string (date-time)
  • invoice
    objectrequired
  • invoice.entity_id
    integerrequired
  • invoice.customer_id
    integerrequired
  • invoice.source_reference
    stringrequired
  • invoice.invoice_date
    string (date)required
  • invoice.posting_date
    string (date)required
  • invoice.due_date
    string (date)required
  • invoice.memo
    string | nullrequired
  • invoice.lines
    object[]required
  • invoice.id
    integerrequired
  • invoice.number
    stringrequired
  • invoice.source_type
    stringrequired
  • invoice.source_id
    integerrequired
  • invoice.source_revision
    integerrequired
  • invoice.revision
    integerrequired
  • invoice.status
    stringrequired
    One of: draft, pending_approval, approved, posted, reversed, cancelled.
  • invoice.currency
    stringrequired
  • invoice.total
    stringrequired
  • invoice.retainage_amount
    stringrequired
  • invoice.current_amount
    stringrequired
  • invoice.open_current
    stringrequired
  • invoice.open_retainage
    stringrequired
  • invoice.prepared_by_id
    integerrequired
  • invoice.approved_by_id
    integer | nullrequired
  • invoice.approved_at
    string (date-time) | nullrequired
  • invoice.journal_entry_id
    integer | nullrequired
  • invoice.paid_current
    stringrequired
  • invoice.paid_retainage
    stringrequired
  • invoice.corrects_invoice_id
    integer | nullrequired
  • invoice.reversal
    object | nullrequired
  • invoice.applications
    object[]required
  • invoice.kind
    stringrequired
    One of: standard, retainage_release, credit_memo.
  • invoice.payment_application_id
    integer | nullrequired
    Owner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
  • invoice.prime_contract_id
    integer | nullrequired
  • invoice.project_id
    integer | nullrequired
  • invoice.released_retainage
    stringrequired
    Retainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
  • invoice.tax_amount
    stringrequired
  • invoice.disputed
    booleanrequired
  • invoice.dispute_reason
    string | nullrequired
  • invoice.credited_current
    stringrequired
    Current AR settled by credit memos, including any sales tax they reverse.
  • invoice.credit_reason
    string | nullrequired
    Credit memos only. One of: return, write_off, discount, tax_adjustment, null.
  • invoice.cancellation_reason
    string | nullrequired
  • invoice.tax_override_reason
    string | nullrequired
  • invoice.tax_warnings
    string[]required
    Sales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
  • invoice.on_account_amount
    string | null
    Credit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
  • invoice.available_credit
    string | null
    Posted, unreversed credit memos: on-account amount less applications and posted refunds.
  • invoice.credit_applications
    object[]
    On-account credit memos applied to this invoice (while each stands).
  • invoice.outside_contract_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
  • 409Stale revision, wrong state, or the sources behind the application changed
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/gmp_applications/1/bill" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "invoice_date": "2026-11-01"
}'

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/certify

Certify a GMP application

Needs ar_approve, by a user who neither prepared nor changed the application. Records the owner's or architect's reviewer and date. Recomputes from the frozen entries: the result must equal what was submitted and certified_amount the current payment due (409 otherwise). Claims its job cost entries (each entry once across applications) and locks the application. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • revision
    integerrequired
  • reviewer_name
    stringrequired
  • reviewer_role
    stringrequired
    One of: owner, architect, owner_representative, lender, other.
  • reviewer_date
    string (date)required
  • certified_amount
    stringrequired
  • note
    string

Response · 200 · object

  • id
    integerrequired
  • prime_contract_id
    integerrequired
  • project_id
    integer
  • entity_id
    integer
  • number
    integerrequired
  • period_end
    string (date)required
  • final
    boolean
  • status
    stringrequired
    One of: draft, submitted, returned, certified, billed, void.
  • revision
    integerrequired
  • exclusions
    object
    Disallowed job cost entries: entry id -> reason.
  • stored
    object[]
  • result
    object | null
    The computed application: summary (G702-style), rows (continuation by cost code), pieces (this period's billing lines), cumulative, disallowed, nteTrims, contingency, allowances, posting (role lines), explain, warnings, errors, inputs.
  • result_hash
    string | null
  • terms_revision
    integer | null
  • earned_to_date
    string
  • retainage_to_date
    string
  • current_due
    stringrequired
  • prepared_by_id
    integer
  • contributor_ids
    integer[]
  • submitted_at
    string | null (date-time)
  • returned_at
    string | null (date-time)
  • return_reason
    string | null
  • certified_by_id
    integer | null
  • certified_at
    string | null (date-time)
  • reviewer_name
    string | null
  • reviewer_role
    string | null
  • reviewer_date
    string | null (date)
  • certification_note
    string | null
  • invoice_id
    integer | null
  • billed_at
    string | null (date-time)
  • voided_at
    string | null (date-time)
  • void_reason
    string | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

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
  • 409Stale revision, wrong state, or the sources behind the application changed
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/gmp_applications/1/certify" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "revision": 1,
  "reviewer_name": "string",
  "reviewer_role": "owner",
  "reviewer_date": "2026-11-01",
  "certified_amount": "0.00"
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/package

GMP application owner package

The owner backup package as one PDF: summary, continuation by cost code, the period's cost register, labor report, disallowed costs, category limits, contingency and allowance position and usage log, stored materials, certification, then the period's AP invoice attachments (PDF pages, PNG/JPEG images). Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · string (binary)

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

Example request

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

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/register

GMP application cost register

The cost detail register: job cost entries of the period (scope=period, default) or to date (scope=to_date), with source document (AP bill, payroll run, journal), cost code, type, amount and disallowed status; paged (page, per_page up to 5000). format=csv returns the to-date register as CSV. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • scope
    stringquery
    One of: period, to_date.
  • page
    integerquery
  • per_page
    integerquery
  • format
    stringquery
    One of: json, csv.

Response · 200 · object

  • total
    integerrequired
  • page
    integer
  • per_page
    integer
  • rows
    object[]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/ar/gmp_applications/1/register" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/return

Return a GMP application

Needs ar_enter. Records that the owner/architect returned a submitted application, with the reason; it is edited and submitted again. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • revision
    integerrequired
  • reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • prime_contract_id
    integerrequired
  • project_id
    integer
  • entity_id
    integer
  • number
    integerrequired
  • period_end
    string (date)required
  • final
    boolean
  • status
    stringrequired
    One of: draft, submitted, returned, certified, billed, void.
  • revision
    integerrequired
  • exclusions
    object
    Disallowed job cost entries: entry id -> reason.
  • stored
    object[]
  • result
    object | null
    The computed application: summary (G702-style), rows (continuation by cost code), pieces (this period's billing lines), cumulative, disallowed, nteTrims, contingency, allowances, posting (role lines), explain, warnings, errors, inputs.
  • result_hash
    string | null
  • terms_revision
    integer | null
  • earned_to_date
    string
  • retainage_to_date
    string
  • current_due
    stringrequired
  • prepared_by_id
    integer
  • contributor_ids
    integer[]
  • submitted_at
    string | null (date-time)
  • returned_at
    string | null (date-time)
  • return_reason
    string | null
  • certified_by_id
    integer | null
  • certified_at
    string | null (date-time)
  • reviewer_name
    string | null
  • reviewer_role
    string | null
  • reviewer_date
    string | null (date)
  • certification_note
    string | null
  • invoice_id
    integer | null
  • billed_at
    string | null (date-time)
  • voided_at
    string | null (date-time)
  • void_reason
    string | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

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
  • 409Stale revision, wrong state, or the sources behind the application changed
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/gmp_applications/1/return" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "revision": 1,
  "reason": "string"
}'

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/submit

Submit a GMP application

Needs ar_enter. Recomputes the application (422 on calc errors such as a net credit or overdrawn contingency), freezes the job cost entries it claims and a hash of its result, and sends it to the owner/architect. The previous application must be billed and the period ended. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • revision
    integerrequired

Response · 200 · object

  • id
    integerrequired
  • prime_contract_id
    integerrequired
  • project_id
    integer
  • entity_id
    integer
  • number
    integerrequired
  • period_end
    string (date)required
  • final
    boolean
  • status
    stringrequired
    One of: draft, submitted, returned, certified, billed, void.
  • revision
    integerrequired
  • exclusions
    object
    Disallowed job cost entries: entry id -> reason.
  • stored
    object[]
  • result
    object | null
    The computed application: summary (G702-style), rows (continuation by cost code), pieces (this period's billing lines), cumulative, disallowed, nteTrims, contingency, allowances, posting (role lines), explain, warnings, errors, inputs.
  • result_hash
    string | null
  • terms_revision
    integer | null
  • earned_to_date
    string
  • retainage_to_date
    string
  • current_due
    stringrequired
  • prepared_by_id
    integer
  • contributor_ids
    integer[]
  • submitted_at
    string | null (date-time)
  • returned_at
    string | null (date-time)
  • return_reason
    string | null
  • certified_by_id
    integer | null
  • certified_at
    string | null (date-time)
  • reviewer_name
    string | null
  • reviewer_role
    string | null
  • reviewer_date
    string | null (date)
  • certification_note
    string | null
  • invoice_id
    integer | null
  • billed_at
    string | null (date-time)
  • voided_at
    string | null (date-time)
  • void_reason
    string | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

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
  • 409Stale revision, wrong state, or the sources behind the application changed
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/gmp_applications/1/submit" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "revision": 1
}'

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/void

Void a GMP application

Needs ar_enter. Voids a draft or returned application with a reason. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • revision
    integerrequired
  • reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • prime_contract_id
    integerrequired
  • project_id
    integer
  • entity_id
    integer
  • number
    integerrequired
  • period_end
    string (date)required
  • final
    boolean
  • status
    stringrequired
    One of: draft, submitted, returned, certified, billed, void.
  • revision
    integerrequired
  • exclusions
    object
    Disallowed job cost entries: entry id -> reason.
  • stored
    object[]
  • result
    object | null
    The computed application: summary (G702-style), rows (continuation by cost code), pieces (this period's billing lines), cumulative, disallowed, nteTrims, contingency, allowances, posting (role lines), explain, warnings, errors, inputs.
  • result_hash
    string | null
  • terms_revision
    integer | null
  • earned_to_date
    string
  • retainage_to_date
    string
  • current_due
    stringrequired
  • prepared_by_id
    integer
  • contributor_ids
    integer[]
  • submitted_at
    string | null (date-time)
  • returned_at
    string | null (date-time)
  • return_reason
    string | null
  • certified_by_id
    integer | null
  • certified_at
    string | null (date-time)
  • reviewer_name
    string | null
  • reviewer_role
    string | null
  • reviewer_date
    string | null (date)
  • certification_note
    string | null
  • invoice_id
    integer | null
  • billed_at
    string | null (date-time)
  • voided_at
    string | null (date-time)
  • void_reason
    string | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

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
  • 409Stale revision, wrong state, or the sources behind the application changed
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/gmp_applications/1/void" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "revision": 1,
  "reason": "string"
}'

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/withdraw

Withdraw a GMP certification

Needs ar_approve. A certified application whose invoice is cancelled or reversed (or that has none) returns to returned and releases its job cost claims; later applications must be voided or withdrawn first. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • revision
    integerrequired
  • reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • prime_contract_id
    integerrequired
  • project_id
    integer
  • entity_id
    integer
  • number
    integerrequired
  • period_end
    string (date)required
  • final
    boolean
  • status
    stringrequired
    One of: draft, submitted, returned, certified, billed, void.
  • revision
    integerrequired
  • exclusions
    object
    Disallowed job cost entries: entry id -> reason.
  • stored
    object[]
  • result
    object | null
    The computed application: summary (G702-style), rows (continuation by cost code), pieces (this period's billing lines), cumulative, disallowed, nteTrims, contingency, allowances, posting (role lines), explain, warnings, errors, inputs.
  • result_hash
    string | null
  • terms_revision
    integer | null
  • earned_to_date
    string
  • retainage_to_date
    string
  • current_due
    stringrequired
  • prepared_by_id
    integer
  • contributor_ids
    integer[]
  • submitted_at
    string | null (date-time)
  • returned_at
    string | null (date-time)
  • return_reason
    string | null
  • certified_by_id
    integer | null
  • certified_at
    string | null (date-time)
  • reviewer_name
    string | null
  • reviewer_role
    string | null
  • reviewer_date
    string | null (date)
  • certification_note
    string | null
  • invoice_id
    integer | null
  • billed_at
    string | null (date-time)
  • voided_at
    string | null (date-time)
  • void_reason
    string | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

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
  • 409Stale revision, wrong state, or the sources behind the application changed
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/gmp_applications/1/withdraw" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "revision": 1,
  "reason": "string"
}'

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/gmp_draws/{id}/decision

Decide a GMP draw

Needs ar_approve, not the proposer. Approves or rejects a proposed draw; an approval that would overdraw its contingency is 409. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • decision
    stringrequired
    One of: approved, rejected.
  • note
    string

Response · 200 · object

  • id
    integer
  • status
    string
  • amount
    string
  • decided_by_id
    integer
  • decided_at
    string (date-time)

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 decided or overdraws the contingency

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/gmp_draws/1/decision" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "decision": "approved"
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/gmp/status

GMP status of a project

For each prime contract on the project with an approved GMP: mode (cost_of_work: applications; sov: progress contract certified through Payment Applications), original and revised GMP, approved changes, committed and actual cost and forecast at completion (job forecast; forecast_error when unavailable), reimbursable and disallowed cost, fee earned, billed to date (posted), retainage held, remaining GMP, contingency and allowance balances, projected savings and the contractor/owner split, last application. Project-scoped grants may read their projects. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • project_id
    integerqueryrequired

Response · 200 · object

  • project_id
    integerrequired
  • contracts
    object[]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/ar/gmp/status" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/invoices

List scoped invoices (default 100, maximum 100 per page)

Lists invoices within the caller entity scope. Requires an accounting view grant. Use returned revision values for subsequent writes. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • page
    integerquery
  • per_page
    integerquery
  • customer_id
    integerquery
  • status
    stringquery
    One of: draft, pending_approval, approved, posted, reversed, cancelled.
  • project_id
    integerquery
    Header or any line on this project
  • date_from
    string (date)query
    Invoice date on or after
  • date_to
    string (date)query
    Invoice date on or before
  • q
    stringquery
    Case-insensitive match on number, source reference or memo
  • overdue
    booleanquery
    true: posted, unreversed invoices with open receivable due before as_of
  • as_of
    string (date)query
    Overdue cutoff (default today)
  • disputed
    booleanquery
  • sort
    stringquery
    One of: date_desc, date_asc, due_asc, due_desc, total_desc, total_asc, number_asc, number_desc.
  • 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[]

  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • source_reference
    stringrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • memo
    string | nullrequired
  • lines
    object[]required
  • lines[].account_id
    integerrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].description
    stringrequired
  • lines[].amount
    stringrequired
  • lines[].retainage_amount
    stringrequired
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].releases_invoice_id
    integer | nullrequired
  • lines[].releases_journal_line_id
    integer | nullrequired
  • lines[].bucket
    string | nullrequired
    One of: current, retainage, null.
  • lines[].tax_code_id
    integer | nullrequired
  • lines[].tax_amount
    stringrequired
  • lines[].payment_application_line_id
    integer | nullrequired
    The pay-app (G703) line a bridged pay-app invoice line bills
  • 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).
  • id
    integerrequired
  • number
    stringrequired
  • source_type
    stringrequired
  • source_id
    integerrequired
  • source_revision
    integerrequired
  • revision
    integerrequired
  • status
    stringrequired
    One of: draft, pending_approval, approved, posted, reversed, cancelled.
  • currency
    stringrequired
  • total
    stringrequired
  • retainage_amount
    stringrequired
  • current_amount
    stringrequired
  • open_current
    stringrequired
  • open_retainage
    stringrequired
  • prepared_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • approved_at
    string (date-time) | nullrequired
  • journal_entry_id
    integer | nullrequired
  • paid_current
    stringrequired
  • paid_retainage
    stringrequired
  • corrects_invoice_id
    integer | nullrequired
  • reversal
    object | nullrequired
  • reversal.id
    integerrequired
  • reversal.source_revision
    integerrequired
  • reversal.posting_date
    string (date)required
  • reversal.reason
    stringrequired
  • reversal.journal_entry_id
    integerrequired
  • reversal.actor_user_id
    integerrequired
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].receipt_id
    integerrequired
  • applications[].receipt_number
    stringrequired
  • applications[].journal_line_id
    integerrequired
  • applications[].bucket
    stringrequired
    One of: current, retainage.
  • applications[].amount
    stringrequired
  • applications[].posting_date
    string (date)required
    The receipt's posting date, or the later cash application's date for rows added after entry.
  • applications[].reversal
    object | nullrequired
  • kind
    stringrequired
    One of: standard, retainage_release, credit_memo.
  • payment_application_id
    integer | nullrequired
    Owner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
  • prime_contract_id
    integer | nullrequired
  • project_id
    integer | nullrequired
  • released_retainage
    stringrequired
    Retainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
  • tax_amount
    stringrequired
  • disputed
    booleanrequired
  • dispute_reason
    string | nullrequired
  • credited_current
    stringrequired
    Current AR settled by credit memos, including any sales tax they reverse.
  • credit_reason
    string | nullrequired
    Credit memos only. One of: return, write_off, discount, tax_adjustment, null.
  • cancellation_reason
    string | nullrequired
  • tax_override_reason
    string | nullrequired
  • tax_warnings
    string[]required
    Sales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
  • on_account_amount
    string | null
    Credit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
  • available_credit
    string | null
    Posted, unreversed credit memos: on-account amount less applications and posted refunds.
  • credit_applications
    object[]
    On-account credit memos applied to this invoice (while each stands).
  • credit_applications[].id
    integer
  • credit_applications[].credit_memo_id
    integer
  • credit_applications[].journal_line_id
    integer
  • credit_applications[].bucket
    string
  • credit_applications[].amount
    string
  • credit_applications[].posting_date
    string (date)
  • outside_contract_reason
    string | nullrequired

Errors

  • 401Authentication required
  • 403Tenant, permission or entity access denied
  • 404Scoped record not found
  • 409State, revision, duplicate source or request conflict
  • 422Invalid input, references, configuration or posting period

Example request

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

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/invoices

Create a draft; a retry with the same request key and payload returns the original invoice

Requires ar_enter. Creates a draft using request_key (UUID). A retry with the same key and identical payload returns 200 with the original invoice; the same key with different data returns 409. Optional correction links an unreplaced reversed invoice and preserves its entity/customer/currency; its posting date must be on or after the reversal. Amounts are exact decimal strings. A standard invoice with a line on a project whose prime contract bills this customer by a non-progress method is 409 (bill it through invoices/from_billing). A correction of a contract billing invoice is 409. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • 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

  • request_key
    string (uuid)required
  • invoice
    objectrequired
  • invoice.entity_id
    integerrequired
  • invoice.customer_id
    integerrequired
  • invoice.source_reference
    stringrequired
  • invoice.invoice_date
    string (date)required
  • invoice.posting_date
    string (date)required
  • invoice.due_date
    string (date) | null
    Omitted or null: invoice date plus the customer profile's payment terms (net 30 without terms).
  • invoice.memo
    string | null
  • invoice.lines
    object[]required
  • invoice.lines[].account_id
    integer | null
    Revenue account; null on a retainage release line. On a credit memo line, the account debited (see credit_reason).
  • invoice.lines[].project_id
    integer | null
  • invoice.lines[].cost_code_id
    integer | null
  • invoice.lines[].description
    stringrequired
  • invoice.lines[].amount
    stringrequired
  • invoice.lines[].retainage_amount
    string
  • invoice.lines[].releases_invoice_id
    integer | null
    Retainage release: posted invoice whose retainage moves to current AR.
  • invoice.lines[].releases_journal_line_id
    integer | null
    Retainage release: that invoice's retainage-receivable journal line (see open_items). Its account, project and cost code are used.
  • invoice.lines[].tax_code_id
    integer | null
    Active sales tax code; its components' rates on the line amount credit their liability accounts and add to current AR. On a credit memo line (not tax_adjustment), the tax is debited back to the liability accounts and credited to the current AR line with the amount. Not on retainage release lines.
  • invoice.lines[].tax_category
    string | null
    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.
  • invoice.lines[].dimension_value_ids
    array | null
    User-defined dimension values (AcctDimensionValue ids), at most one per dimension; see oas-dimensions.json.
  • invoice.kind
    string
    retainage_release: every line releases open retainage (Dr AR_CONTROL / Cr RETAINAGE_RECEIVABLE, no revenue), refused above the open retainage. credit_memo: every line credits open receivable of a posted invoice (Dr the line account, plus the tax code's liability when the line has one / Cr AR or retainage for amount plus tax), refused above the line's open amount. One of: standard, retainage_release, credit_memo.
  • invoice.credit_reason
    string | null
    Credit memos only (null means return). return: lines debit revenue accounts. write_off and discount: lines may also debit expense accounts (bad debt, discounts) or a contra-asset allowance. tax_adjustment: lines debit a sales tax liability account directly and carry no tax code. One of: return, write_off, discount, tax_adjustment, null.
  • invoice.tax_override_reason
    string | null
    Charges sales tax that the job tax profile (consumer-model state) or a valid customer exemption certificate forbids. Without it such an invoice is refused with 422; with it the findings are kept in tax_warnings and the independent approver accepts the override (the approval audit event records the reason and approver).
  • invoice.outside_contract_reason
    string | null
    A standard invoice to the owner of a live (not deleted or terminated) prime contract, any billing method, is 409 unless it gives this reason for billing outside the contract; the independent approver accepts it (the approval audit event records the reason and approver). A manual invoice on a non-progress contract's project is 409 even with a reason (bill it through ar/invoices/from_billing).
  • correction
    object
  • correction.invoice_id
    integerrequired
  • correction.revision
    integerrequired

Response · 200 · object

  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • source_reference
    stringrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • memo
    string | nullrequired
  • lines
    object[]required
  • lines[].account_id
    integerrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].description
    stringrequired
  • lines[].amount
    stringrequired
  • lines[].retainage_amount
    stringrequired
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].releases_invoice_id
    integer | nullrequired
  • lines[].releases_journal_line_id
    integer | nullrequired
  • lines[].bucket
    string | nullrequired
    One of: current, retainage, null.
  • lines[].tax_code_id
    integer | nullrequired
  • lines[].tax_amount
    stringrequired
  • lines[].payment_application_line_id
    integer | nullrequired
    The pay-app (G703) line a bridged pay-app invoice line bills
  • 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).
  • id
    integerrequired
  • number
    stringrequired
  • source_type
    stringrequired
  • source_id
    integerrequired
  • source_revision
    integerrequired
  • revision
    integerrequired
  • status
    stringrequired
    One of: draft, pending_approval, approved, posted, reversed, cancelled.
  • currency
    stringrequired
  • total
    stringrequired
  • retainage_amount
    stringrequired
  • current_amount
    stringrequired
  • open_current
    stringrequired
  • open_retainage
    stringrequired
  • prepared_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • approved_at
    string (date-time) | nullrequired
  • journal_entry_id
    integer | nullrequired
  • paid_current
    stringrequired
  • paid_retainage
    stringrequired
  • corrects_invoice_id
    integer | nullrequired
  • reversal
    object | nullrequired
  • reversal.id
    integerrequired
  • reversal.source_revision
    integerrequired
  • reversal.posting_date
    string (date)required
  • reversal.reason
    stringrequired
  • reversal.journal_entry_id
    integerrequired
  • reversal.actor_user_id
    integerrequired
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].receipt_id
    integerrequired
  • applications[].receipt_number
    stringrequired
  • applications[].journal_line_id
    integerrequired
  • applications[].bucket
    stringrequired
    One of: current, retainage.
  • applications[].amount
    stringrequired
  • applications[].posting_date
    string (date)required
    The receipt's posting date, or the later cash application's date for rows added after entry.
  • applications[].reversal
    object | nullrequired
  • kind
    stringrequired
    One of: standard, retainage_release, credit_memo.
  • payment_application_id
    integer | nullrequired
    Owner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
  • prime_contract_id
    integer | nullrequired
  • project_id
    integer | nullrequired
  • released_retainage
    stringrequired
    Retainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
  • tax_amount
    stringrequired
  • disputed
    booleanrequired
  • dispute_reason
    string | nullrequired
  • credited_current
    stringrequired
    Current AR settled by credit memos, including any sales tax they reverse.
  • credit_reason
    string | nullrequired
    Credit memos only. One of: return, write_off, discount, tax_adjustment, null.
  • cancellation_reason
    string | nullrequired
  • tax_override_reason
    string | nullrequired
  • tax_warnings
    string[]required
    Sales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
  • on_account_amount
    string | null
    Credit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
  • available_credit
    string | null
    Posted, unreversed credit memos: on-account amount less applications and posted refunds.
  • credit_applications
    object[]
    On-account credit memos applied to this invoice (while each stands).
  • credit_applications[].id
    integer
  • credit_applications[].credit_memo_id
    integer
  • credit_applications[].journal_line_id
    integer
  • credit_applications[].bucket
    string
  • credit_applications[].amount
    string
  • credit_applications[].posting_date
    string (date)
  • outside_contract_reason
    string | nullrequired

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Tenant, permission or entity access denied
  • 404Scoped record not found
  • 409State, revision, duplicate source or request conflict
  • 422Invalid input, references, configuration or posting period

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/invoices" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "request_key": "00000000-0000-4000-8000-000000000000",
  "invoice": {
    "entity_id": 1,
    "customer_id": 1,
    "source_reference": "string",
    "invoice_date": "2026-11-01",
    "posting_date": "2026-11-01",
    "lines": [
      {
        "description": "string",
        "amount": "0.00"
      }
    ]
  }
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}

Get scoped invoice

Returns the scoped invoice, current revision, lines and reversal/correction metadata. An excluded or absent source returns 404. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • source_reference
    stringrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • memo
    string | nullrequired
  • lines
    object[]required
  • lines[].account_id
    integerrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].description
    stringrequired
  • lines[].amount
    stringrequired
  • lines[].retainage_amount
    stringrequired
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].releases_invoice_id
    integer | nullrequired
  • lines[].releases_journal_line_id
    integer | nullrequired
  • lines[].bucket
    string | nullrequired
    One of: current, retainage, null.
  • lines[].tax_code_id
    integer | nullrequired
  • lines[].tax_amount
    stringrequired
  • lines[].payment_application_line_id
    integer | nullrequired
    The pay-app (G703) line a bridged pay-app invoice line bills
  • 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).
  • id
    integerrequired
  • number
    stringrequired
  • source_type
    stringrequired
  • source_id
    integerrequired
  • source_revision
    integerrequired
  • revision
    integerrequired
  • status
    stringrequired
    One of: draft, pending_approval, approved, posted, reversed, cancelled.
  • currency
    stringrequired
  • total
    stringrequired
  • retainage_amount
    stringrequired
  • current_amount
    stringrequired
  • open_current
    stringrequired
  • open_retainage
    stringrequired
  • prepared_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • approved_at
    string (date-time) | nullrequired
  • journal_entry_id
    integer | nullrequired
  • paid_current
    stringrequired
  • paid_retainage
    stringrequired
  • corrects_invoice_id
    integer | nullrequired
  • reversal
    object | nullrequired
  • reversal.id
    integerrequired
  • reversal.source_revision
    integerrequired
  • reversal.posting_date
    string (date)required
  • reversal.reason
    stringrequired
  • reversal.journal_entry_id
    integerrequired
  • reversal.actor_user_id
    integerrequired
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].receipt_id
    integerrequired
  • applications[].receipt_number
    stringrequired
  • applications[].journal_line_id
    integerrequired
  • applications[].bucket
    stringrequired
    One of: current, retainage.
  • applications[].amount
    stringrequired
  • applications[].posting_date
    string (date)required
    The receipt's posting date, or the later cash application's date for rows added after entry.
  • applications[].reversal
    object | nullrequired
  • kind
    stringrequired
    One of: standard, retainage_release, credit_memo.
  • payment_application_id
    integer | nullrequired
    Owner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
  • prime_contract_id
    integer | nullrequired
  • project_id
    integer | nullrequired
  • released_retainage
    stringrequired
    Retainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
  • tax_amount
    stringrequired
  • disputed
    booleanrequired
  • dispute_reason
    string | nullrequired
  • credited_current
    stringrequired
    Current AR settled by credit memos, including any sales tax they reverse.
  • credit_reason
    string | nullrequired
    Credit memos only. One of: return, write_off, discount, tax_adjustment, null.
  • cancellation_reason
    string | nullrequired
  • tax_override_reason
    string | nullrequired
  • tax_warnings
    string[]required
    Sales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
  • on_account_amount
    string | null
    Credit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
  • available_credit
    string | null
    Posted, unreversed credit memos: on-account amount less applications and posted refunds.
  • credit_applications
    object[]
    On-account credit memos applied to this invoice (while each stands).
  • credit_applications[].id
    integer
  • credit_applications[].credit_memo_id
    integer
  • credit_applications[].journal_line_id
    integer
  • credit_applications[].bucket
    string
  • credit_applications[].amount
    string
  • credit_applications[].posting_date
    string (date)
  • outside_contract_reason
    string | nullrequired

Errors

  • 401Authentication required
  • 403Tenant, permission or entity access denied
  • 404Scoped record not found
  • 409State, revision, duplicate source or request conflict
  • 422Invalid input, references, configuration or posting period

Example request

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

Accounting / Accounts Receivable

PATCH /rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}

Replace current draft revision; all editors are excluded from approval

Requires ar_enter. Replaces the current draft using top-level revision and a complete invoice object, including all lines; this is not an AP-style partial patch. A successful edit increments revision. A stale revision or non-draft state returns 409. Posted documents are corrected through reversal and a linked new draft. Pay-app and contract billing invoices (prime_contract_id set) are 409: cancel and bill again. A standard invoice with a line on a project whose prime contract bills this customer by a non-progress method is 409. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • revision
    integerrequired
  • invoice
    objectrequired
  • invoice.entity_id
    integerrequired
  • invoice.customer_id
    integerrequired
  • invoice.source_reference
    stringrequired
  • invoice.invoice_date
    string (date)required
  • invoice.posting_date
    string (date)required
  • invoice.due_date
    string (date) | null
    Omitted or null: invoice date plus the customer profile's payment terms (net 30 without terms).
  • invoice.memo
    string | null
  • invoice.lines
    object[]required
  • invoice.lines[].account_id
    integer | null
    Revenue account; null on a retainage release line. On a credit memo line, the account debited (see credit_reason).
  • invoice.lines[].project_id
    integer | null
  • invoice.lines[].cost_code_id
    integer | null
  • invoice.lines[].description
    stringrequired
  • invoice.lines[].amount
    stringrequired
  • invoice.lines[].retainage_amount
    string
  • invoice.lines[].releases_invoice_id
    integer | null
    Retainage release: posted invoice whose retainage moves to current AR.
  • invoice.lines[].releases_journal_line_id
    integer | null
    Retainage release: that invoice's retainage-receivable journal line (see open_items). Its account, project and cost code are used.
  • invoice.lines[].tax_code_id
    integer | null
    Active sales tax code; its components' rates on the line amount credit their liability accounts and add to current AR. On a credit memo line (not tax_adjustment), the tax is debited back to the liability accounts and credited to the current AR line with the amount. Not on retainage release lines.
  • invoice.lines[].tax_category
    string | null
    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.
  • invoice.lines[].dimension_value_ids
    array | null
    User-defined dimension values (AcctDimensionValue ids), at most one per dimension; see oas-dimensions.json.
  • invoice.kind
    string
    retainage_release: every line releases open retainage (Dr AR_CONTROL / Cr RETAINAGE_RECEIVABLE, no revenue), refused above the open retainage. credit_memo: every line credits open receivable of a posted invoice (Dr the line account, plus the tax code's liability when the line has one / Cr AR or retainage for amount plus tax), refused above the line's open amount. One of: standard, retainage_release, credit_memo.
  • invoice.credit_reason
    string | null
    Credit memos only (null means return). return: lines debit revenue accounts. write_off and discount: lines may also debit expense accounts (bad debt, discounts) or a contra-asset allowance. tax_adjustment: lines debit a sales tax liability account directly and carry no tax code. One of: return, write_off, discount, tax_adjustment, null.
  • invoice.tax_override_reason
    string | null
    Charges sales tax that the job tax profile (consumer-model state) or a valid customer exemption certificate forbids. Without it such an invoice is refused with 422; with it the findings are kept in tax_warnings and the independent approver accepts the override (the approval audit event records the reason and approver).
  • invoice.outside_contract_reason
    string | null
    A standard invoice to the owner of a live (not deleted or terminated) prime contract, any billing method, is 409 unless it gives this reason for billing outside the contract; the independent approver accepts it (the approval audit event records the reason and approver). A manual invoice on a non-progress contract's project is 409 even with a reason (bill it through ar/invoices/from_billing).

Response · 200 · object

  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • source_reference
    stringrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • memo
    string | nullrequired
  • lines
    object[]required
  • lines[].account_id
    integerrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].description
    stringrequired
  • lines[].amount
    stringrequired
  • lines[].retainage_amount
    stringrequired
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].releases_invoice_id
    integer | nullrequired
  • lines[].releases_journal_line_id
    integer | nullrequired
  • lines[].bucket
    string | nullrequired
    One of: current, retainage, null.
  • lines[].tax_code_id
    integer | nullrequired
  • lines[].tax_amount
    stringrequired
  • lines[].payment_application_line_id
    integer | nullrequired
    The pay-app (G703) line a bridged pay-app invoice line bills
  • 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).
  • id
    integerrequired
  • number
    stringrequired
  • source_type
    stringrequired
  • source_id
    integerrequired
  • source_revision
    integerrequired
  • revision
    integerrequired
  • status
    stringrequired
    One of: draft, pending_approval, approved, posted, reversed, cancelled.
  • currency
    stringrequired
  • total
    stringrequired
  • retainage_amount
    stringrequired
  • current_amount
    stringrequired
  • open_current
    stringrequired
  • open_retainage
    stringrequired
  • prepared_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • approved_at
    string (date-time) | nullrequired
  • journal_entry_id
    integer | nullrequired
  • paid_current
    stringrequired
  • paid_retainage
    stringrequired
  • corrects_invoice_id
    integer | nullrequired
  • reversal
    object | nullrequired
  • reversal.id
    integerrequired
  • reversal.source_revision
    integerrequired
  • reversal.posting_date
    string (date)required
  • reversal.reason
    stringrequired
  • reversal.journal_entry_id
    integerrequired
  • reversal.actor_user_id
    integerrequired
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].receipt_id
    integerrequired
  • applications[].receipt_number
    stringrequired
  • applications[].journal_line_id
    integerrequired
  • applications[].bucket
    stringrequired
    One of: current, retainage.
  • applications[].amount
    stringrequired
  • applications[].posting_date
    string (date)required
    The receipt's posting date, or the later cash application's date for rows added after entry.
  • applications[].reversal
    object | nullrequired
  • kind
    stringrequired
    One of: standard, retainage_release, credit_memo.
  • payment_application_id
    integer | nullrequired
    Owner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
  • prime_contract_id
    integer | nullrequired
  • project_id
    integer | nullrequired
  • released_retainage
    stringrequired
    Retainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
  • tax_amount
    stringrequired
  • disputed
    booleanrequired
  • dispute_reason
    string | nullrequired
  • credited_current
    stringrequired
    Current AR settled by credit memos, including any sales tax they reverse.
  • credit_reason
    string | nullrequired
    Credit memos only. One of: return, write_off, discount, tax_adjustment, null.
  • cancellation_reason
    string | nullrequired
  • tax_override_reason
    string | nullrequired
  • tax_warnings
    string[]required
    Sales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
  • on_account_amount
    string | null
    Credit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
  • available_credit
    string | null
    Posted, unreversed credit memos: on-account amount less applications and posted refunds.
  • credit_applications
    object[]
    On-account credit memos applied to this invoice (while each stands).
  • credit_applications[].id
    integer
  • credit_applications[].credit_memo_id
    integer
  • credit_applications[].journal_line_id
    integer
  • credit_applications[].bucket
    string
  • credit_applications[].amount
    string
  • credit_applications[].posting_date
    string (date)
  • outside_contract_reason
    string | nullrequired

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Tenant, permission or entity access denied
  • 404Scoped record not found
  • 409State, revision, duplicate source or request conflict
  • 422Invalid input, references, configuration or posting period

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/invoices/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "revision": 1,
  "invoice": {
    "entity_id": 1,
    "customer_id": 1,
    "source_reference": "string",
    "invoice_date": "2026-11-01",
    "posting_date": "2026-11-01",
    "lines": [
      {
        "description": "string",
        "amount": "0.00"
      }
    ]
  }
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/attachments

List attachments on a AR invoice

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/ar/invoices/1/attachments" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/attachments

Attach a file to a AR invoice

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 ar_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/ar/invoices/1/attachments" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "file": "string"
}'

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/credit_applications

Apply a posted on-account credit memo to open invoice lines (Dr AR control / Cr receivable line). arApprove; idempotent by request_key.

Applies the credit memo's available on-account credit (on-account lines less earlier applications and posted refunds) to open receivable lines of the same entity, customer and currency. The credit memo's preparer or contributors cannot place it (403, segregation of duties). More than available or open is 409. Reversing the credit memo reverses its applications. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • 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

  • request_key
    string (uuid)required
  • posting_date
    string (date)required
  • applications
    object[]required
  • applications[].invoice_id
    integerrequired
  • applications[].invoice_revision
    integerrequired
  • applications[].journal_line_id
    integerrequired
  • applications[].bucket
    stringrequired
    One of: current, retainage.
  • applications[].amount
    stringrequired

Response · 201 · object[]

  • id
    integerrequired
  • credit_memo_id
    integerrequired
  • invoice_id
    integerrequired
  • invoice_revision
    integer
  • journal_line_id
    integerrequired
  • bucket
    stringrequired
    One of: current, retainage.
  • amount
    stringrequired
  • posting_date
    string (date)required
  • journal_entry_id
    integerrequired
  • actor_user_id
    integer

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or separation of duties denied
  • 404Scoped source not found
  • 409State, revision, overapplication or idempotency conflict
  • 422Invalid data, dates, account or closed period

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/invoices/1/credit_applications" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "request_key": "00000000-0000-4000-8000-000000000000",
  "posting_date": "2026-11-01",
  "applications": [
    {
      "invoice_id": 1,
      "invoice_revision": 1,
      "journal_line_id": 1,
      "bucket": "current",
      "amount": "0.00"
    }
  ]
}'

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/dispute

Flag or clear a collections dispute on a posted invoice. Disputed invoices age in the Disputed column. arEnter.

Flag or clear a collections dispute on a posted invoice. Disputed invoices age in the Disputed column. arEnter. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • disputed
    booleanrequired
  • reason
    string | null
    Required when disputed.

Response · 200 · object

  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • source_reference
    stringrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • memo
    string | nullrequired
  • lines
    object[]required
  • lines[].account_id
    integerrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].description
    stringrequired
  • lines[].amount
    stringrequired
  • lines[].retainage_amount
    stringrequired
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].releases_invoice_id
    integer | nullrequired
  • lines[].releases_journal_line_id
    integer | nullrequired
  • lines[].bucket
    string | nullrequired
    One of: current, retainage, null.
  • lines[].tax_code_id
    integer | nullrequired
  • lines[].tax_amount
    stringrequired
  • lines[].payment_application_line_id
    integer | nullrequired
    The pay-app (G703) line a bridged pay-app invoice line bills
  • 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).
  • id
    integerrequired
  • number
    stringrequired
  • source_type
    stringrequired
  • source_id
    integerrequired
  • source_revision
    integerrequired
  • revision
    integerrequired
  • status
    stringrequired
    One of: draft, pending_approval, approved, posted, reversed, cancelled.
  • currency
    stringrequired
  • total
    stringrequired
  • retainage_amount
    stringrequired
  • current_amount
    stringrequired
  • open_current
    stringrequired
  • open_retainage
    stringrequired
  • prepared_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • approved_at
    string (date-time) | nullrequired
  • journal_entry_id
    integer | nullrequired
  • paid_current
    stringrequired
  • paid_retainage
    stringrequired
  • corrects_invoice_id
    integer | nullrequired
  • reversal
    object | nullrequired
  • reversal.id
    integerrequired
  • reversal.source_revision
    integerrequired
  • reversal.posting_date
    string (date)required
  • reversal.reason
    stringrequired
  • reversal.journal_entry_id
    integerrequired
  • reversal.actor_user_id
    integerrequired
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].receipt_id
    integerrequired
  • applications[].receipt_number
    stringrequired
  • applications[].journal_line_id
    integerrequired
  • applications[].bucket
    stringrequired
    One of: current, retainage.
  • applications[].amount
    stringrequired
  • applications[].posting_date
    string (date)required
    The receipt's posting date, or the later cash application's date for rows added after entry.
  • applications[].reversal
    object | nullrequired
  • kind
    stringrequired
    One of: standard, retainage_release, credit_memo.
  • payment_application_id
    integer | nullrequired
    Owner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
  • prime_contract_id
    integer | nullrequired
  • project_id
    integer | nullrequired
  • released_retainage
    stringrequired
    Retainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
  • tax_amount
    stringrequired
  • disputed
    booleanrequired
  • dispute_reason
    string | nullrequired
  • credited_current
    stringrequired
    Current AR settled by credit memos, including any sales tax they reverse.
  • credit_reason
    string | nullrequired
    Credit memos only. One of: return, write_off, discount, tax_adjustment, null.
  • cancellation_reason
    string | nullrequired
  • tax_override_reason
    string | nullrequired
  • tax_warnings
    string[]required
    Sales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
  • on_account_amount
    string | null
    Credit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
  • available_credit
    string | null
    Posted, unreversed credit memos: on-account amount less applications and posted refunds.
  • credit_applications
    object[]
    On-account credit memos applied to this invoice (while each stands).
  • credit_applications[].id
    integer
  • credit_applications[].credit_memo_id
    integer
  • credit_applications[].journal_line_id
    integer
  • credit_applications[].bucket
    string
  • credit_applications[].amount
    string
  • credit_applications[].posting_date
    string (date)
  • outside_contract_reason
    string | nullrequired

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or separation of duties denied
  • 404Scoped source not found
  • 409State, revision, overapplication or idempotency conflict
  • 422Invalid data, dates, account or closed period

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/invoices/1/dispute" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "disputed": true
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/pdf

Invoice PDF

Any accounting viewer in the invoice's entity. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · string (binary)

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

Example request

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

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/reverse

Append a source-owned reversal. Independent arApprove required. Identical retries return the original reversal.

Requires ar_approve independent of preparer/contributors, current revision, UUID request_key, date and reason. Only posted invoices can be reversed. First reverse all active applied receipts; invoice reversal cannot precede those reversals or original posting. Reconciled bank lines block reversal. The date must be in an open period. Matching retries return the same reversal; changed key/date/reason conflicts. Create a linked correction separately. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • 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

  • request_key
    string (uuid)required
  • revision
    integerrequired
  • date
    string (date)required
  • reason
    stringrequired
  • nsf
    boolean
    Receipt returned by the bank (NSF): unwinds later applications and, when deposited, takes the item back out of the bank. Audited as nsf_returned.

Response · 200 · object | null

  • id
    integerrequired
  • source_revision
    integerrequired
  • posting_date
    string (date)required
  • reason
    stringrequired
  • journal_entry_id
    integerrequired
  • actor_user_id
    integerrequired

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or separation of duties denied
  • 404Scoped source not found
  • 409State, revision, overapplication or idempotency conflict
  • 422Invalid data, dates, account or closed period

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/invoices/1/reverse" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "request_key": "00000000-0000-4000-8000-000000000000",
  "revision": 1,
  "date": "2026-11-01",
  "reason": "string"
}'

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/send

Queue a posted invoice for email to the customer's billing contact, with the invoice PDF attached.

Commits an audit row (send_queued) and an outbox job in one transaction and returns 202 without contacting the email provider, so the company posting lock is never held on email latency. The job runner then emails the invoice with its PDF attached as the queuing user (AR read access is rechecked), retries a failed send with backoff, skips an invoice reversed in the meantime, and audits 'sent'. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 202 · object

  • invoice_id
    integerrequired
  • to
    stringrequired
  • job_id
    integerrequired
  • 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
  • 409Conflict
  • 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/ar/invoices/1/send" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/transition

Submit, return to draft, independently approve, or post an invoice

Requires revision and action. submit: draft to pending_approval (ar_enter); return: pending_approval to draft with reason and incremented revision (ar_approve); approve: pending_approval to approved (ar_approve, independent of preparer and all contributors); post: approved to posted (ar_enter). Posting revalidates accounts and period. An identical post retry at the current posted revision returns the existing invoice; do not assume every transition is retryable. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • revision
    integerrequired
  • action
    stringrequired
    One of: submit, return, approve, post, cancel.
  • reason
    string

Response · 200 · object

  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • source_reference
    stringrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • memo
    string | nullrequired
  • lines
    object[]required
  • lines[].account_id
    integerrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].description
    stringrequired
  • lines[].amount
    stringrequired
  • lines[].retainage_amount
    stringrequired
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].releases_invoice_id
    integer | nullrequired
  • lines[].releases_journal_line_id
    integer | nullrequired
  • lines[].bucket
    string | nullrequired
    One of: current, retainage, null.
  • lines[].tax_code_id
    integer | nullrequired
  • lines[].tax_amount
    stringrequired
  • lines[].payment_application_line_id
    integer | nullrequired
    The pay-app (G703) line a bridged pay-app invoice line bills
  • 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).
  • id
    integerrequired
  • number
    stringrequired
  • source_type
    stringrequired
  • source_id
    integerrequired
  • source_revision
    integerrequired
  • revision
    integerrequired
  • status
    stringrequired
    One of: draft, pending_approval, approved, posted, reversed, cancelled.
  • currency
    stringrequired
  • total
    stringrequired
  • retainage_amount
    stringrequired
  • current_amount
    stringrequired
  • open_current
    stringrequired
  • open_retainage
    stringrequired
  • prepared_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • approved_at
    string (date-time) | nullrequired
  • journal_entry_id
    integer | nullrequired
  • paid_current
    stringrequired
  • paid_retainage
    stringrequired
  • corrects_invoice_id
    integer | nullrequired
  • reversal
    object | nullrequired
  • reversal.id
    integerrequired
  • reversal.source_revision
    integerrequired
  • reversal.posting_date
    string (date)required
  • reversal.reason
    stringrequired
  • reversal.journal_entry_id
    integerrequired
  • reversal.actor_user_id
    integerrequired
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].receipt_id
    integerrequired
  • applications[].receipt_number
    stringrequired
  • applications[].journal_line_id
    integerrequired
  • applications[].bucket
    stringrequired
    One of: current, retainage.
  • applications[].amount
    stringrequired
  • applications[].posting_date
    string (date)required
    The receipt's posting date, or the later cash application's date for rows added after entry.
  • applications[].reversal
    object | nullrequired
  • kind
    stringrequired
    One of: standard, retainage_release, credit_memo.
  • payment_application_id
    integer | nullrequired
    Owner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
  • prime_contract_id
    integer | nullrequired
  • project_id
    integer | nullrequired
  • released_retainage
    stringrequired
    Retainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
  • tax_amount
    stringrequired
  • disputed
    booleanrequired
  • dispute_reason
    string | nullrequired
  • credited_current
    stringrequired
    Current AR settled by credit memos, including any sales tax they reverse.
  • credit_reason
    string | nullrequired
    Credit memos only. One of: return, write_off, discount, tax_adjustment, null.
  • cancellation_reason
    string | nullrequired
  • tax_override_reason
    string | nullrequired
  • tax_warnings
    string[]required
    Sales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
  • on_account_amount
    string | null
    Credit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
  • available_credit
    string | null
    Posted, unreversed credit memos: on-account amount less applications and posted refunds.
  • credit_applications
    object[]
    On-account credit memos applied to this invoice (while each stands).
  • credit_applications[].id
    integer
  • credit_applications[].credit_memo_id
    integer
  • credit_applications[].journal_line_id
    integer
  • credit_applications[].bucket
    string
  • credit_applications[].amount
    string
  • credit_applications[].posting_date
    string (date)
  • outside_contract_reason
    string | nullrequired

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Tenant, permission or entity access denied
  • 404Scoped record not found
  • 409State, revision, duplicate source or request conflict
  • 422Invalid input, references, configuration or posting period

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/invoices/1/transition" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "revision": 1,
  "action": "submit"
}'

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/invoices/from_billing

Draft an AR invoice from a non-progress billing

Needs ar_enter. The prime contract's billing_method (tm, cost_plus, unit_price, gmp, milestone) must match billing.method; progress contracts bill by certified pay app (409). Caps, fees, markups, rates, retainage, unit items and the milestone schedule come only from the contract's approved billing terms (prime_contracts/{id}/billing_terms; 422 when none are approved); the request carries this period's facts. The calc in calc/billing.ts prices the period; its billed amounts become revenue lines with its retainage spread over them, and the draft follows submit, approve and post. NTE and GMP caps, the GMP settlement, the cost-plus fee billed before (fee cap and fixed fee) and each unit-price item's previous quantity read what AR already billed on the contract; fee_billed_before and previous_quantity only count when higher. A T&M ticket_id or cost-plus cost id already on a live (non-cancelled, unreversed) invoice of the contract is 409, as is a second GMP settlement. The resulting draft cannot be edited (cancel and bill again). A credit period is refused (enter a credit memo). Idempotent on request_key: same body replays (200), another body is 409. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Request body

  • request_key
    string (uuid)required
  • prime_contract_id
    integerrequired
  • entity_id
    integer
  • revenue_account_id
    integer
  • invoice_date
    string (date)required
  • posting_date
    string (date)
  • due_date
    string (date)
  • source_reference
    string
  • memo
    string
  • billing
    objectrequired
  • billing.method
    anyrequired
  • billing.input
    objectrequired
  • billing.input.lines
    object[]required
  • billing.input.lines[].id
    stringrequired
  • billing.input.lines[].ticket_id
    string
  • billing.input.lines[].cost_type
    stringrequired
    One of: labor, material, equipment, subcontract, other.
  • billing.input.lines[].description
    stringrequired
  • billing.input.lines[].quantity
    string
  • billing.input.lines[].rate_code
    string
    Prices quantity at the terms' labor_rates entry (422 when unknown). Without rate_code give cost; labor needs a rate_code when the terms define labor_rates, and a line with rate_code takes no cost (422).
  • billing.input.lines[].cost
    string
  • billing.input.lines[].taxable
    boolean
  • billing.input.tax_code_id
    integer

Response · 200 · object

  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • source_reference
    stringrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • memo
    string | nullrequired
  • lines
    object[]required
  • lines[].account_id
    integerrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].description
    stringrequired
  • lines[].amount
    stringrequired
  • lines[].retainage_amount
    stringrequired
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].releases_invoice_id
    integer | nullrequired
  • lines[].releases_journal_line_id
    integer | nullrequired
  • lines[].bucket
    string | nullrequired
    One of: current, retainage, null.
  • lines[].tax_code_id
    integer | nullrequired
  • lines[].tax_amount
    stringrequired
  • lines[].payment_application_line_id
    integer | nullrequired
    The pay-app (G703) line a bridged pay-app invoice line bills
  • 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).
  • id
    integerrequired
  • number
    stringrequired
  • source_type
    stringrequired
  • source_id
    integerrequired
  • source_revision
    integerrequired
  • revision
    integerrequired
  • status
    stringrequired
    One of: draft, pending_approval, approved, posted, reversed, cancelled.
  • currency
    stringrequired
  • total
    stringrequired
  • retainage_amount
    stringrequired
  • current_amount
    stringrequired
  • open_current
    stringrequired
  • open_retainage
    stringrequired
  • prepared_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • approved_at
    string (date-time) | nullrequired
  • journal_entry_id
    integer | nullrequired
  • paid_current
    stringrequired
  • paid_retainage
    stringrequired
  • corrects_invoice_id
    integer | nullrequired
  • reversal
    object | nullrequired
  • reversal.id
    integerrequired
  • reversal.source_revision
    integerrequired
  • reversal.posting_date
    string (date)required
  • reversal.reason
    stringrequired
  • reversal.journal_entry_id
    integerrequired
  • reversal.actor_user_id
    integerrequired
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].receipt_id
    integerrequired
  • applications[].receipt_number
    stringrequired
  • applications[].journal_line_id
    integerrequired
  • applications[].bucket
    stringrequired
    One of: current, retainage.
  • applications[].amount
    stringrequired
  • applications[].posting_date
    string (date)required
    The receipt's posting date, or the later cash application's date for rows added after entry.
  • applications[].reversal
    object | nullrequired
  • kind
    stringrequired
    One of: standard, retainage_release, credit_memo.
  • payment_application_id
    integer | nullrequired
    Owner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
  • prime_contract_id
    integer | nullrequired
  • project_id
    integer | nullrequired
  • released_retainage
    stringrequired
    Retainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
  • tax_amount
    stringrequired
  • disputed
    booleanrequired
  • dispute_reason
    string | nullrequired
  • credited_current
    stringrequired
    Current AR settled by credit memos, including any sales tax they reverse.
  • credit_reason
    string | nullrequired
    Credit memos only. One of: return, write_off, discount, tax_adjustment, null.
  • cancellation_reason
    string | nullrequired
  • tax_override_reason
    string | nullrequired
  • tax_warnings
    string[]required
    Sales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
  • on_account_amount
    string | null
    Credit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
  • available_credit
    string | null
    Posted, unreversed credit memos: on-account amount less applications and posted refunds.
  • credit_applications
    object[]
    On-account credit memos applied to this invoice (while each stands).
  • credit_applications[].id
    integer
  • credit_applications[].credit_memo_id
    integer
  • credit_applications[].journal_line_id
    integer
  • credit_applications[].bucket
    string
  • credit_applications[].amount
    string
  • credit_applications[].posting_date
    string (date)
  • outside_contract_reason
    string | nullrequired
  • calc
    object
  • calc.retainage
    string
  • calc.explain
    any

Errors

  • 400Malformed JSON request body
  • 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 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/ar/invoices/from_billing" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "request_key": "00000000-0000-4000-8000-000000000000",
  "prime_contract_id": 1,
  "invoice_date": "2026-11-01",
  "billing": {
    "method": null,
    "input": {
      "lines": [
        {
          "id": "string",
          "cost_type": "labor",
          "description": "string"
        }
      ]
    }
  }
}'

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/invoices/from_payment_application

Bill a certified owner pay app in AR (once per pay app)

Requires ar_enter. Creates the draft AR invoice for an approved or paid prime-contract pay app, billed to the contract owner. The pay app is re-performed with the G702 calculator against retainage already billed for the contract and must reproduce its current payment due (line 8); posting debits AR_CONTROL line 8 and RETAINAGE_RECEIVABLE the change in line 5 and credits revenue the period billing. Retainage released on the pay app becomes release lines against the contract's earlier pay-app invoices. Earlier certified pay apps on the contract must already be billed and posted. A repeat call returns 200 with the same invoice. Billing again after the pay app's invoice is reversed creates a new draft linked as that invoice's correction; after a cancel, a new draft. A certified zero-billing pay app needs no invoice. A negative pay app bridges as a credit memo against the earlier pay-app invoices' open AR and retainage. A pay app on a contract whose billing_method is not progress is 409 (it bills through ar/invoices/from_billing). Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Request body

  • payment_application_id
    integerrequired
  • entity_id
    integer
    Defaults to the entity the project is assigned to (job cost scope), else the accounting default entity; another entity than the project's is refused.
  • revenue_account_id
    integer
    Defaults to the CONTRACT_REVENUE account.
  • invoice_date
    string (date)
    Defaults to the pay app billing date, else period end.
  • posting_date
    string (date)
    Defaults to invoice_date (a re-bill after reversal: no earlier than the reversal date).
  • due_date
    string (date)
    Defaults to invoice_date plus the owner's profile terms (net 30 without terms).
  • dimension_value_ids
    integer[]
    User-defined dimension values (one per dimension) for the revenue lines. A pay-app invoice cannot be edited, so a dimension its revenue account requires must be given here.

Response · 200 · object

  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • source_reference
    stringrequired
  • invoice_date
    string (date)required
  • posting_date
    string (date)required
  • due_date
    string (date)required
  • memo
    string | nullrequired
  • lines
    object[]required
  • lines[].account_id
    integerrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].description
    stringrequired
  • lines[].amount
    stringrequired
  • lines[].retainage_amount
    stringrequired
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].releases_invoice_id
    integer | nullrequired
  • lines[].releases_journal_line_id
    integer | nullrequired
  • lines[].bucket
    string | nullrequired
    One of: current, retainage, null.
  • lines[].tax_code_id
    integer | nullrequired
  • lines[].tax_amount
    stringrequired
  • lines[].payment_application_line_id
    integer | nullrequired
    The pay-app (G703) line a bridged pay-app invoice line bills
  • 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).
  • id
    integerrequired
  • number
    stringrequired
  • source_type
    stringrequired
  • source_id
    integerrequired
  • source_revision
    integerrequired
  • revision
    integerrequired
  • status
    stringrequired
    One of: draft, pending_approval, approved, posted, reversed, cancelled.
  • currency
    stringrequired
  • total
    stringrequired
  • retainage_amount
    stringrequired
  • current_amount
    stringrequired
  • open_current
    stringrequired
  • open_retainage
    stringrequired
  • prepared_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • approved_at
    string (date-time) | nullrequired
  • journal_entry_id
    integer | nullrequired
  • paid_current
    stringrequired
  • paid_retainage
    stringrequired
  • corrects_invoice_id
    integer | nullrequired
  • reversal
    object | nullrequired
  • reversal.id
    integerrequired
  • reversal.source_revision
    integerrequired
  • reversal.posting_date
    string (date)required
  • reversal.reason
    stringrequired
  • reversal.journal_entry_id
    integerrequired
  • reversal.actor_user_id
    integerrequired
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].receipt_id
    integerrequired
  • applications[].receipt_number
    stringrequired
  • applications[].journal_line_id
    integerrequired
  • applications[].bucket
    stringrequired
    One of: current, retainage.
  • applications[].amount
    stringrequired
  • applications[].posting_date
    string (date)required
    The receipt's posting date, or the later cash application's date for rows added after entry.
  • applications[].reversal
    object | nullrequired
  • kind
    stringrequired
    One of: standard, retainage_release, credit_memo.
  • payment_application_id
    integer | nullrequired
    Owner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
  • prime_contract_id
    integer | nullrequired
  • project_id
    integer | nullrequired
  • released_retainage
    stringrequired
    Retainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
  • tax_amount
    stringrequired
  • disputed
    booleanrequired
  • dispute_reason
    string | nullrequired
  • credited_current
    stringrequired
    Current AR settled by credit memos, including any sales tax they reverse.
  • credit_reason
    string | nullrequired
    Credit memos only. One of: return, write_off, discount, tax_adjustment, null.
  • cancellation_reason
    string | nullrequired
  • tax_override_reason
    string | nullrequired
  • tax_warnings
    string[]required
    Sales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
  • on_account_amount
    string | null
    Credit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
  • available_credit
    string | null
    Posted, unreversed credit memos: on-account amount less applications and posted refunds.
  • credit_applications
    object[]
    On-account credit memos applied to this invoice (while each stands).
  • credit_applications[].id
    integer
  • credit_applications[].credit_memo_id
    integer
  • credit_applications[].journal_line_id
    integer
  • credit_applications[].bucket
    string
  • credit_applications[].amount
    string
  • credit_applications[].posting_date
    string (date)
  • outside_contract_reason
    string | nullrequired

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Tenant, permission or entity access denied
  • 404Scoped record not found
  • 409State, revision, duplicate source or request conflict
  • 422Invalid input, references, configuration or posting period

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/invoices/from_payment_application" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "payment_application_id": 1
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/payment_applications/{id}/pdf

G702/G703 PDF of a certified owner pay app

Accounting viewers with view access to the project's pay apps. Application summary and continuation sheet with the industry form's math and column letters, neutral wording (no AIA form text). 409 before the pay app is certified; 422 for a commitment pay app. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · string (binary)

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
  • 409Conflict
  • 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/ar/payment_applications/1/pdf" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Receivable

PUT /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/billing_method

Set a prime contract's billing method

Needs ar_approve (not a project-scoped grant). progress bills by certified pay app; tm, cost_plus, unit_price, gmp and milestone bill through ar/invoices/from_billing. Once the contract has a non-cancelled AR invoice or a certified (approved or paid) pay app, a change is 409 unless conversion_reason is given. Audited with the reason and those counts. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • billing_method
    stringrequired
    One of: progress, tm, cost_plus, unit_price, gmp, milestone.
  • conversion_reason
    string | null
    Why a contract already billed changes method.

Response · 200 · object

  • id
    integerrequired
  • billing_method
    stringrequired
    One of: progress, tm, cost_plus, unit_price, gmp, milestone.

Errors

  • 400Malformed JSON request body
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
  • 404Not found in this company
  • 409The contract is already billed and no conversion reason was given
  • 422Validation failed or the ledger refused the change

Example request

Generated from the contractcurl
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/prime_contracts/1/billing_method" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "billing_method": "progress"
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/billing_terms

Get a prime contract's billing terms

The approved billing terms and any proposed change waiting for approval. Refused (403) to project-scoped grants. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • prime_contract_id
    integerrequired
  • billing_method
    stringrequired
    One of: progress, tm, cost_plus, unit_price, gmp, milestone.
  • contract_retainage_pct
    string | nullrequired
  • revision
    integerrequired
    0 before any terms are proposed; approve names the revision it approves.
  • terms
    object | nullrequired
    The approved terms billing uses (null: none; billing is then 422).
  • approved_by_id
    integer | nullrequired
  • approved_at
    string (date-time) | nullrequired
  • proposed
    object | nullrequired
    A change waiting for approval (unit_items carry the snapshotted bid).
  • proposed_by_id
    integer | nullrequired
  • proposed_at
    string (date-time) | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, project-scoped grant, or wrong company
  • 404Not found in this company

Example request

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

Accounting / Accounts Receivable

PUT /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/billing_terms

Propose a prime contract's billing terms

Needs ar_enter (not a project-scoped grant). Stores the body as the proposed terms and increments revision; the approved terms stay in force until an ar_approve user other than the proposer approves (billing_terms/approve). Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • nte
    string | null
    T&M not-to-exceed; null is uncapped.
  • markups
    object
    T&M markup percent by cost type (labor, material, equipment, subcontract, other).
  • labor_rates
    object[]
    T&M rates a ticket line prices its quantity at (rate_code); codes are unique.
  • labor_rates[].code
    stringrequired
  • labor_rates[].rate
    stringrequired
  • gmp
    string | null
    Cost-plus guaranteed maximum price (cumulative cost plus fee billed is capped at it), and the GMP settlement's.
  • fee
    object | null
    {kind: pct, pct, pct_by_cost_type?, cap_amount?} or {kind: fixed, amount, basis: poc | schedule}. The GMP settlement needs a pct fee.
  • savings_share_pct
    string | null
    GMP settlement: the contractor's share of savings below the GMP.
  • retainage_pct
    string | null
    Null: the prime contract's retainage_percent.
  • unit_items
    object[]
    Unit-price items: the contract's line items; their quantity, unit cost, unit and description are snapshotted as the bid when proposed (422 for a line item of another contract or one without quantity and unit cost).
  • unit_items[].prime_contract_line_item_id
    integerrequired
  • unit_items[].tolerance_pct
    string
  • contract_amount
    string | null
    Milestone billing: the amount the percent milestones split.
  • milestones
    object[]
    Milestone schedule; ids are unique.
  • milestones[].id
    stringrequired
  • milestones[].name
    stringrequired
  • milestones[].pct
    string
  • milestones[].amount
    string
  • gmp_setup
    object | null
    GMP contract provisions for cost-of-work applications (cost_plus contracts with a gmp): fee_on_change_orders_pct (fixed fee), general_conditions ({mode: cost} or {mode: lump_sum, amount, cost_code_ids}), contingency ({contractor_amount, owner_amount}), allowances ([{key, name, amount, cost_code_ids}]), markups ([{name, pct, basis: cost|cost_plus_fee}]), category_nte ([{cost_type, amount}]), non_reimbursable_cost_code_ids, burden_reimbursable (default true), retainage_step_down ({at_pct, reduced_pct}), stored_retainage_pct.
  • gmp_setup.fee_on_change_orders_pct
    string | null
  • gmp_setup.general_conditions
    object | null
  • gmp_setup.contingency
    object | null
  • gmp_setup.allowances
    object[]
  • gmp_setup.markups
    object[]
  • gmp_setup.category_nte
    object[]
  • gmp_setup.non_reimbursable_cost_code_ids
    integer[]
  • gmp_setup.burden_reimbursable
    boolean
  • gmp_setup.retainage_step_down
    object | null
  • gmp_setup.stored_retainage_pct
    string | null

Response · 200 · object

  • prime_contract_id
    integerrequired
  • billing_method
    stringrequired
    One of: progress, tm, cost_plus, unit_price, gmp, milestone.
  • contract_retainage_pct
    string | nullrequired
  • revision
    integerrequired
    0 before any terms are proposed; approve names the revision it approves.
  • terms
    object | nullrequired
    The approved terms billing uses (null: none; billing is then 422).
  • approved_by_id
    integer | nullrequired
  • approved_at
    string (date-time) | nullrequired
  • proposed
    object | nullrequired
    A change waiting for approval (unit_items carry the snapshotted bid).
  • proposed_by_id
    integer | nullrequired
  • proposed_at
    string (date-time) | nullrequired

Errors

  • 400Malformed JSON request body
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, project-scoped grant, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/prime_contracts/1/billing_terms" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "nte": "string",
  "gmp": "string",
  "savings_share_pct": "string"
}'

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/billing_terms/approve

Approve a prime contract's proposed billing terms

Needs ar_approve, and the approver must not be the user who proposed the change (403, segregation of duties). revision must be the proposed revision (409 when it changed, or when nothing is proposed). The proposed terms become the terms billing uses. Audited with the before and after terms. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • revision
    integerrequired

Response · 200 · object

  • prime_contract_id
    integerrequired
  • billing_method
    stringrequired
    One of: progress, tm, cost_plus, unit_price, gmp, milestone.
  • contract_retainage_pct
    string | nullrequired
  • revision
    integerrequired
    0 before any terms are proposed; approve names the revision it approves.
  • terms
    object | nullrequired
    The approved terms billing uses (null: none; billing is then 422).
  • approved_by_id
    integer | nullrequired
  • approved_at
    string (date-time) | nullrequired
  • proposed
    object | nullrequired
    A change waiting for approval (unit_items carry the snapshotted bid).
  • proposed_by_id
    integer | nullrequired
  • proposed_at
    string (date-time) | nullrequired

Errors

  • 400Malformed JSON request body
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, segregation of duties, project-scoped grant, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Nothing proposed, or the proposed revision changed
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/prime_contracts/1/billing_terms/approve" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "revision": 1
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/closeout

Get a prime contract's closeout documents

Lists the contract's final retainage requirements and which are received or missing. Empty lists indicate no checklist when restricted_submittal_evidence is absent. Linked revision IDs and approval status require Submittals view on the project and submittals:read for scoped tokens. Refused (403) to project-scoped grants. Requires accounting:read.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • prime_contract_id
    integerrequired
  • required
    string[]required
  • received
    string[]required
  • missing
    string[]required
  • restricted_submittal_evidence
    boolean
    When true, the response contains only manual checks because submittal evidence is restricted.

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/ar/prime_contracts/1/closeout" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Receivable

PUT /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/closeout

Set a prime contract's closeout documents

Needs ar_approve and accounting:write. required lists at least one manual check or exact submittal:<revision ID> reference. received lists manual checks on file. Saving a checklist with new or existing references needs Submittals view and submittals:read for a scoped token. A final retainage release returns 422 at bridge, submit or post until every required item is complete. Audited.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • required
    string[]required
  • received
    string[]

Response · 200 · object

  • prime_contract_id
    integerrequired
  • required
    string[]required
  • received
    string[]required
  • missing
    string[]required

Errors

  • 400Malformed JSON request body
  • 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 PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/prime_contracts/1/closeout" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "required": []
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/gmp_applications

List a GMP contract's applications

Cost-of-work applications of a cost_plus prime contract with approved GMP terms, newest first. 409 when the contract is not a cost_plus GMP contract. Refused (403) to project-scoped grants. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • contract
    objectrequired
  • terms_revision
    integer | null
  • applications
    object[]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
  • 409Not a cost_plus GMP contract

Example request

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

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/gmp_applications

Start a GMP application

Needs ar_enter. Starts the contract's next application (draft) for the period ending period_end from posted job cost of the contract's job and entity: every job cost entry through the period end that no earlier certified application claimed. The previous application must be billed; one open application per contract (a repeat is 409). Refused when the contract has invoices outside applications. final: fee and lump-sum general conditions fully earned and the contractor's savings share billed. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • 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

  • period_end
    string (date)required
  • final
    boolean

Response · 201 · object

  • id
    integerrequired
  • prime_contract_id
    integerrequired
  • project_id
    integer
  • entity_id
    integer
  • number
    integerrequired
  • period_end
    string (date)required
  • final
    boolean
  • status
    stringrequired
    One of: draft, submitted, returned, certified, billed, void.
  • revision
    integerrequired
  • exclusions
    object
    Disallowed job cost entries: entry id -> reason.
  • stored
    object[]
  • result
    object | null
    The computed application: summary (G702-style), rows (continuation by cost code), pieces (this period's billing lines), cumulative, disallowed, nteTrims, contingency, allowances, posting (role lines), explain, warnings, errors, inputs.
  • result_hash
    string | null
  • terms_revision
    integer | null
  • earned_to_date
    string
  • retainage_to_date
    string
  • current_due
    stringrequired
  • prepared_by_id
    integer
  • contributor_ids
    integer[]
  • submitted_at
    string | null (date-time)
  • returned_at
    string | null (date-time)
  • return_reason
    string | null
  • certified_by_id
    integer | null
  • certified_at
    string | null (date-time)
  • reviewer_name
    string | null
  • reviewer_role
    string | null
  • reviewer_date
    string | null (date)
  • certification_note
    string | null
  • invoice_id
    integer | null
  • billed_at
    string | null (date-time)
  • voided_at
    string | null (date-time)
  • void_reason
    string | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

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
  • 409Stale revision, wrong state, or the sources behind the application changed
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/prime_contracts/1/gmp_applications" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "period_end": "2026-11-01"
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/gmp_closeout

GMP close-out reconciliation

Final reconciliation from the last certified application: revised GMP, cost plus fee, savings and the contractor/owner split or the overrun absorbed, final price, billed to date (AR, posted and all live), final billing still due, retainage held, the closeout checklist and readiness flags. Refused (403) to project-scoped grants. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • prime_contract_id
    integerrequired
  • last_application
    object | null
  • reconciliation
    objectrequired
  • billed_to_date
    string
  • billed_posted
    string
  • closeout
    object
  • ready
    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

Example request

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

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/gmp_draws

List GMP contingency and allowance draws

The usage log of the GMP contract's contingency transfers and allowance adjustments. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • draws
    object[]
  • draws[].id
    integer
  • draws[].prime_contract_id
    integer
  • draws[].source
    string
    One of: contractor_contingency, owner_contingency, allowance.
  • draws[].allowance_key
    string | null
  • draws[].cost_code_id
    integer | null
  • draws[].amount
    string
  • draws[].reason
    string
  • draws[].reference
    string | null
  • draws[].status
    string
    One of: proposed, approved, rejected.
  • draws[].proposed_by_id
    integer
  • draws[].decided_by_id
    integer | null
  • draws[].decided_at
    string | null (date-time)
  • draws[].decision_note
    string | null
  • draws[].created_at
    string (date-time)

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/ar/prime_contracts/1/gmp_draws" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/gmp_draws

Propose a GMP contingency or allowance draw

Needs ar_enter. A contingency transfer (contractor_contingency or owner_contingency, positive, to a cost code of the project) moves GMP budget to that code; an allowance adjustment (allowance_key of the GMP terms, signed) changes the allowance. Takes effect when another user approves it. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • 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

  • source
    stringrequired
    One of: contractor_contingency, owner_contingency, allowance.
  • allowance_key
    string | null
  • cost_code_id
    integer | null
  • amount
    stringrequired
  • reason
    stringrequired
  • reference
    string

Response · 201 · object

  • id
    integer
  • prime_contract_id
    integer
  • source
    string
    One of: contractor_contingency, owner_contingency, allowance.
  • allowance_key
    string | null
  • cost_code_id
    integer | null
  • amount
    string
  • reason
    string
  • reference
    string | null
  • status
    string
    One of: proposed, approved, rejected.
  • proposed_by_id
    integer
  • decided_by_id
    integer | null
  • decided_at
    string | null (date-time)
  • decision_note
    string | null
  • created_at
    string (date-time)

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/ar/prime_contracts/1/gmp_draws" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "source": "contractor_contingency",
  "amount": "0.00",
  "reason": "string"
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/receipts

Receipt history, 50 per page

Lists scoped receipts, optionally filtered by customer_id, in pages of per_page (default 50). Pagination headers include Total, Per-Page and Link. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • page
    integerquery
  • customer_id
    integerquery
  • per_page
    integerquery

Response · 200 · object[]

  • id
    integerrequired
  • number
    stringrequired
  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • reference
    stringrequired
  • posting_date
    string (date)required
  • currency
    stringrequired
  • amount
    stringrequired
  • cash_account_id
    integerrequired
  • revision
    integerrequired
  • source_type
    stringrequired
  • source_id
    integerrequired
  • source_revision
    integerrequired
  • status
    stringrequired
    One of: draft, approved, posted, reversed, cancelled.
  • prepared_by_id
    integerrequired
  • contributor_ids
    integer[]required
  • approved_by_id
    integer | nullrequired
  • approved_at
    string (date-time) | nullrequired
  • journal_entry_id
    integer | nullrequired
  • corrects_receipt_id
    integer | nullrequired
  • reversal
    object | nullrequired
  • reversal.id
    integerrequired
  • reversal.source_revision
    integerrequired
  • reversal.posting_date
    string (date)required
  • reversal.reason
    stringrequired
  • reversal.journal_entry_id
    integerrequired
  • reversal.actor_user_id
    integerrequired
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].invoice_id
    integerrequired
  • applications[].invoice_revision
    integerrequired
  • applications[].journal_line_id
    integerrequired
  • applications[].bucket
    stringrequired
    One of: current, retainage.
  • applications[].amount
    stringrequired
    Negative only on the from-side of a transfer.
  • applications[].cash_application_id
    integer | null
    Null for allocations made at entry.
  • cancellation_reason
    string | nullrequired
  • method
    string
    One of: check, ach, wire, card, cash, other.
  • check_no
    string | null
  • payer
    string | null
  • unapplied_amount
    string
    Cash still held in CUSTOMER_DEPOSITS (entry remainder less later applications).

Errors

  • 401Authentication required
  • 403Scope or separation of duties denied
  • 404Scoped source not found
  • 409State, revision, overapplication or idempotency conflict
  • 422Invalid data, dates, account or closed period

Example request

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

Accounting / Accounts Receivable

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

Record a fully allocated draft; matching request-key retries return the original receipt

Requires ar_enter. Creates a draft with UUID request_key and exact decimal string amount. Allocations must sum exactly to the receipt; unapplied cash is not supported. Each allocation identifies invoice_id, invoice_revision, journal_line_id and current or retainage bucket from open_items. Matching-key matching-payload retries return the original; changed payload conflicts. There is no receipt PATCH: cancel an unposted receipt or reverse a posted receipt, then create a linked correction using a new request key and reference. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • 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

  • request_key
    string (uuid)required
  • receipt
    objectrequired
  • receipt.entity_id
    integerrequired
  • receipt.customer_id
    integerrequired
  • receipt.cash_account_id
    integerrequired
  • receipt.reference
    stringrequired
  • receipt.posting_date
    string (date)required
  • receipt.amount
    stringrequired
  • receipt.applications
    object[]required
    Allocations at entry; any remainder of amount posts to CUSTOMER_DEPOSITS as unapplied cash.
  • receipt.applications[].invoice_id
    integerrequired
  • receipt.applications[].invoice_revision
    integerrequired
  • receipt.applications[].journal_line_id
    integerrequired
  • receipt.applications[].bucket
    stringrequired
    One of: current, retainage.
  • receipt.applications[].amount
    stringrequired
  • receipt.correction
    object | null
  • receipt.correction.receipt_id
    integerrequired
  • receipt.correction.revision
    integerrequired
  • receipt.method
    string
    One of: check, ach, wire, card, cash, other.
  • receipt.check_no
    string | null
  • receipt.payer
    string | null

Response · 201 · object

  • id
    integerrequired
  • number
    stringrequired
  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • reference
    stringrequired
  • posting_date
    string (date)required
  • currency
    stringrequired
  • amount
    stringrequired
  • cash_account_id
    integerrequired
  • revision
    integerrequired
  • source_type
    stringrequired
  • source_id
    integerrequired
  • source_revision
    integerrequired
  • status
    stringrequired
    One of: draft, approved, posted, reversed, cancelled.
  • prepared_by_id
    integerrequired
  • contributor_ids
    integer[]required
  • approved_by_id
    integer | nullrequired
  • approved_at
    string (date-time) | nullrequired
  • journal_entry_id
    integer | nullrequired
  • corrects_receipt_id
    integer | nullrequired
  • reversal
    object | nullrequired
  • reversal.id
    integerrequired
  • reversal.source_revision
    integerrequired
  • reversal.posting_date
    string (date)required
  • reversal.reason
    stringrequired
  • reversal.journal_entry_id
    integerrequired
  • reversal.actor_user_id
    integerrequired
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].invoice_id
    integerrequired
  • applications[].invoice_revision
    integerrequired
  • applications[].journal_line_id
    integerrequired
  • applications[].bucket
    stringrequired
    One of: current, retainage.
  • applications[].amount
    stringrequired
    Negative only on the from-side of a transfer.
  • applications[].cash_application_id
    integer | null
    Null for allocations made at entry.
  • cancellation_reason
    string | nullrequired
  • method
    string
    One of: check, ach, wire, card, cash, other.
  • check_no
    string | null
  • payer
    string | null
  • unapplied_amount
    string
    Cash still held in CUSTOMER_DEPOSITS (entry remainder less later applications).

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or separation of duties denied
  • 404Scoped source not found
  • 409State, revision, overapplication or idempotency conflict
  • 422Invalid data, dates, account or closed period

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/receipts" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "request_key": "00000000-0000-4000-8000-000000000000",
  "receipt": {
    "entity_id": 1,
    "customer_id": 1,
    "cash_account_id": 1,
    "reference": "string",
    "posting_date": "2026-11-01",
    "amount": "0.00",
    "applications": [
      {
        "invoice_id": 1,
        "invoice_revision": 1,
        "journal_line_id": 1,
        "bucket": "current",
        "amount": "0.00"
      }
    ]
  }
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/receipts/{id}

Receipt detail and immutable applications

Returns a scoped receipt with allocations and reversal/correction links; excluded or absent receipts return 404. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • reference
    stringrequired
  • posting_date
    string (date)required
  • currency
    stringrequired
  • amount
    stringrequired
  • cash_account_id
    integerrequired
  • revision
    integerrequired
  • source_type
    stringrequired
  • source_id
    integerrequired
  • source_revision
    integerrequired
  • status
    stringrequired
    One of: draft, approved, posted, reversed, cancelled.
  • prepared_by_id
    integerrequired
  • contributor_ids
    integer[]required
  • approved_by_id
    integer | nullrequired
  • approved_at
    string (date-time) | nullrequired
  • journal_entry_id
    integer | nullrequired
  • corrects_receipt_id
    integer | nullrequired
  • reversal
    object | nullrequired
  • reversal.id
    integerrequired
  • reversal.source_revision
    integerrequired
  • reversal.posting_date
    string (date)required
  • reversal.reason
    stringrequired
  • reversal.journal_entry_id
    integerrequired
  • reversal.actor_user_id
    integerrequired
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].invoice_id
    integerrequired
  • applications[].invoice_revision
    integerrequired
  • applications[].journal_line_id
    integerrequired
  • applications[].bucket
    stringrequired
    One of: current, retainage.
  • applications[].amount
    stringrequired
    Negative only on the from-side of a transfer.
  • applications[].cash_application_id
    integer | null
    Null for allocations made at entry.
  • cancellation_reason
    string | nullrequired
  • method
    string
    One of: check, ach, wire, card, cash, other.
  • check_no
    string | null
  • payer
    string | null
  • unapplied_amount
    string
    Cash still held in CUSTOMER_DEPOSITS (entry remainder less later applications).

Errors

  • 401Authentication required
  • 403Scope or separation of duties denied
  • 404Scoped source not found
  • 409State, revision, overapplication or idempotency conflict
  • 422Invalid data, dates, account or closed period

Example request

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

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/receipts/{id}/applications

Apply a posted receipt's unapplied cash to open invoice lines, or transfer its allocations between lines. arApprove; idempotent by request_key.

Apply a posted receipt's unapplied cash to open invoice lines, or transfer its allocations between lines. arApprove; idempotent by request_key. The receipt's preparer or contributors cannot apply or transfer its cash (403, segregation of duties). Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • 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

  • request_key
    string (uuid)required
  • kind
    stringrequired
    apply: positive amounts from unapplied cash (Dr CUSTOMER_DEPOSITS / Cr receivable). transfer: signed amounts netting to zero that move this receipt's allocations between lines. One of: apply, transfer.
  • posting_date
    string (date)required
  • applications
    object[]required
  • applications[].invoice_id
    integerrequired
  • applications[].invoice_revision
    integerrequired
  • applications[].journal_line_id
    integerrequired
  • applications[].bucket
    stringrequired
    One of: current, retainage.
  • applications[].amount
    stringrequired

Response · 201 · object

  • id
    integer
  • receipt_id
    integer
  • kind
    string
    One of: apply, transfer.
  • posting_date
    string (date)
  • journal_entry_id
    integer
  • actor_user_id
    integer
  • applications
    object[]
  • applications[].id
    integer
  • applications[].invoice_id
    integer
  • applications[].journal_line_id
    integer
  • applications[].bucket
    string
  • applications[].amount
    string

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or separation of duties denied
  • 404Scoped source not found
  • 409State, revision, overapplication or idempotency conflict
  • 422Invalid data, dates, account or closed period

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/receipts/1/applications" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "request_key": "00000000-0000-4000-8000-000000000000",
  "kind": "apply",
  "posting_date": "2026-11-01",
  "applications": [
    {
      "invoice_id": 1,
      "invoice_revision": 1,
      "journal_line_id": 1,
      "bucket": "current",
      "amount": "0.00"
    }
  ]
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/receipts/{id}/attachments

List attachments on a AR receipt

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/ar/receipts/1/attachments" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/receipts/{id}/attachments

Attach a file to a AR receipt

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 ar_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/ar/receipts/1/attachments" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "file": "string"
}'

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/receipts/{id}/reverse

Append a source-owned reversal. Independent arApprove required. Identical retries return the original reversal.

Requires ar_approve independent of preparer/contributors, current revision, UUID request_key, date and reason. Reverses posted cash and restores invoice bucket availability. Reversal cannot precede posting and must use an open period; reconciled bank lines block it. Matching retries return the original reversal; changed request data conflicts. A replacement receipt must link the reversed receipt, preserve entity/customer/currency and not predate reversal. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • 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

  • request_key
    string (uuid)required
  • revision
    integerrequired
  • date
    string (date)required
  • reason
    stringrequired
  • nsf
    boolean
    Receipt returned by the bank (NSF): unwinds later applications and, when deposited, takes the item back out of the bank. Audited as nsf_returned.

Response · 200 · object | null

  • id
    integerrequired
  • source_revision
    integerrequired
  • posting_date
    string (date)required
  • reason
    stringrequired
  • journal_entry_id
    integerrequired
  • actor_user_id
    integerrequired

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or separation of duties denied
  • 404Scoped source not found
  • 409State, revision, overapplication or idempotency conflict
  • 422Invalid data, dates, account or closed period

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/receipts/1/reverse" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "request_key": "00000000-0000-4000-8000-000000000000",
  "revision": 1,
  "date": "2026-11-01",
  "reason": "string"
}'

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/receipts/{id}/transition

Independently approve or post; balances are revalidated under the company lock

Requires current revision. approve moves draft to approved and requires ar_approve independent of preparer/contributors. post requires ar_enter and approved state; it rechecks open amounts, invoice provenance and cash account before posting atomically. Retrying post on the same posted revision returns the existing receipt. cancel needs a reason: draft cancellation requires ar_enter; approved cancellation requires independent ar_approve. Posted receipts must be reversed. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • revision
    integerrequired
  • action
    stringrequired
    One of: approve, post, cancel.
  • reason
    string

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • reference
    stringrequired
  • posting_date
    string (date)required
  • currency
    stringrequired
  • amount
    stringrequired
  • cash_account_id
    integerrequired
  • revision
    integerrequired
  • source_type
    stringrequired
  • source_id
    integerrequired
  • source_revision
    integerrequired
  • status
    stringrequired
    One of: draft, approved, posted, reversed, cancelled.
  • prepared_by_id
    integerrequired
  • contributor_ids
    integer[]required
  • approved_by_id
    integer | nullrequired
  • approved_at
    string (date-time) | nullrequired
  • journal_entry_id
    integer | nullrequired
  • corrects_receipt_id
    integer | nullrequired
  • reversal
    object | nullrequired
  • reversal.id
    integerrequired
  • reversal.source_revision
    integerrequired
  • reversal.posting_date
    string (date)required
  • reversal.reason
    stringrequired
  • reversal.journal_entry_id
    integerrequired
  • reversal.actor_user_id
    integerrequired
  • applications
    object[]required
  • applications[].id
    integerrequired
  • applications[].invoice_id
    integerrequired
  • applications[].invoice_revision
    integerrequired
  • applications[].journal_line_id
    integerrequired
  • applications[].bucket
    stringrequired
    One of: current, retainage.
  • applications[].amount
    stringrequired
    Negative only on the from-side of a transfer.
  • applications[].cash_application_id
    integer | null
    Null for allocations made at entry.
  • cancellation_reason
    string | nullrequired
  • method
    string
    One of: check, ach, wire, card, cash, other.
  • check_no
    string | null
  • payer
    string | null
  • unapplied_amount
    string
    Cash still held in CUSTOMER_DEPOSITS (entry remainder less later applications).

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or separation of duties denied
  • 404Scoped source not found
  • 409State, revision, overapplication or idempotency conflict
  • 422Invalid data, dates, account or closed period

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/receipts/1/transition" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "revision": 1,
  "action": "approve"
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/receipts/open_items

Open original AR distributions for one customer/entity; pages over open invoices only, oldest due first

Requires ar_enter and permitted entity_id/customer_id. Returns current open invoice journal lines with revision, bucket and exact open amount. These are current-state amounts only: no historical cutoff reconstruction or tie-out certification. Refresh before allocating; approval and posting revalidate available amounts. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • entity_id
    integerqueryrequired
  • customer_id
    integerqueryrequired
  • page
    integerquery
  • per_page
    integerquery
  • currency
    stringquery
    Receipt currency (ISO 4217). Defaults to the entity's functional currency; a foreign currency lists the invoices billed in it and the cash accounts denominated in it.

Response · 200 · object

  • total
    integerrequired
  • currency
    stringrequired
  • accounts
    object[]required
  • accounts[].id
    integerrequired
  • accounts[].number
    stringrequired
  • accounts[].name
    stringrequired
  • items
    object[]required
  • items[].invoice_id
    integerrequired
  • items[].invoice_number
    stringrequired
  • items[].due_date
    string (date)required
  • items[].invoice_revision
    integerrequired
  • items[].journal_line_id
    integerrequired
  • items[].bucket
    stringrequired
    One of: current, retainage.
  • items[].description
    string | nullrequired
  • items[].project_id
    integer | nullrequired
  • items[].open
    stringrequired
  • per_page
    integerrequired

Errors

  • 401Authentication required
  • 403Scope or separation of duties denied
  • 404Scoped source not found
  • 409State, revision, overapplication or idempotency conflict
  • 422Invalid data, dates, account or closed period

Example request

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

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/refunds

Customer refunds, newest first (paginated).

Refunds in the caller's entities; project-scoped grants are refused. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • customer_id
    integerquery
  • page
    integerquery
  • per_page
    integerquery

Response · 200 · object[]

  • id
    integerrequired
  • number
    stringrequired
  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • receipt_id
    integer | null
  • credit_memo_id
    integer | null
  • amount
    stringrequired
  • currency
    string
  • bank_account_id
    integer
  • posting_date
    string (date)required
  • method
    string
  • reference
    string | null
  • memo
    string | null
  • status
    stringrequired
    One of: draft, posted, cancelled, reversed.
  • prepared_by_id
    integer
  • approved_by_id
    integer | null
  • approved_at
    string | null (date-time)
  • journal_entry_id
    integer | null
  • reason
    string | null
  • reversal_entry_id
    integer | null
  • reversal_date
    string | null (date)

Errors

  • 401Authentication required
  • 403Scope or separation of duties denied
  • 404Scoped source not found

Example request

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

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/refunds

Draft a refund of customer credit: a posted receipt's unapplied cash or an on-account credit memo. arEnter; idempotent by request_key.

The amount may not exceed the credit available now (409); drafts reserve nothing and are rechecked at posting. Posting is a separate independent step. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • 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

  • request_key
    string (uuid)required
  • refund
    objectrequired
    Exactly one of receipt_id (its unapplied cash) or credit_memo_id (an on-account credit memo).
  • refund.receipt_id
    integer | null
  • refund.credit_memo_id
    integer | null
  • refund.bank_account_id
    integerrequired
  • refund.posting_date
    string (date)required
  • refund.amount
    stringrequired
  • refund.method
    string
    One of: check, ach, wire, card, cash, other.
  • refund.reference
    string | null
  • refund.memo
    string | null

Response · 201 · object

  • id
    integerrequired
  • number
    stringrequired
  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • receipt_id
    integer | null
  • credit_memo_id
    integer | null
  • amount
    stringrequired
  • currency
    string
  • bank_account_id
    integer
  • posting_date
    string (date)required
  • method
    string
  • reference
    string | null
  • memo
    string | null
  • status
    stringrequired
    One of: draft, posted, cancelled, reversed.
  • prepared_by_id
    integer
  • approved_by_id
    integer | null
  • approved_at
    string | null (date-time)
  • journal_entry_id
    integer | null
  • reason
    string | null
  • reversal_entry_id
    integer | null
  • reversal_date
    string | null (date)

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or separation of duties denied
  • 404Scoped source not found
  • 409State, revision, overapplication or idempotency conflict
  • 422Invalid data, dates, account or closed period

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/refunds" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "request_key": "00000000-0000-4000-8000-000000000000",
  "refund": {
    "bank_account_id": 1,
    "posting_date": "2026-11-01",
    "amount": "0.00"
  }
}'

Accounting / Accounts Receivable

GET /rest/v1.0/companies/{company_id}/accounting/ar/refunds/{id}

Refund detail.

Refund in the caller's entities. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • receipt_id
    integer | null
  • credit_memo_id
    integer | null
  • amount
    stringrequired
  • currency
    string
  • bank_account_id
    integer
  • posting_date
    string (date)required
  • method
    string
  • reference
    string | null
  • memo
    string | null
  • status
    stringrequired
    One of: draft, posted, cancelled, reversed.
  • prepared_by_id
    integer
  • approved_by_id
    integer | null
  • approved_at
    string | null (date-time)
  • journal_entry_id
    integer | null
  • reason
    string | null
  • reversal_entry_id
    integer | null
  • reversal_date
    string | null (date)

Errors

  • 401Authentication required
  • 403Scope or separation of duties denied
  • 404Scoped source not found

Example request

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

Accounting / Accounts Receivable

POST /rest/v1.0/companies/{company_id}/accounting/ar/refunds/{id}/transition

Post, cancel or reverse a customer refund.

post: an arApprove user other than the preparer (403 otherwise) approves and posts Dr CUSTOMER_DEPOSITS (receipt) or AR control (credit memo) / Cr the bank account, after rechecking the available credit (409). cancel: a draft, with a reason (arEnter). reverse: a posted refund, with a reason and date (arApprove, not the preparer); posts the reversing entry. A matching retry of a completed transition returns the refund. A receipt or credit memo with a posted refund cannot be reversed until the refund is. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • action
    stringrequired
    One of: post, cancel, reverse.
  • reason
    string
    Required to cancel or reverse.
  • date
    string (date)
    Reversal date (reverse only).

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • entity_id
    integerrequired
  • customer_id
    integerrequired
  • receipt_id
    integer | null
  • credit_memo_id
    integer | null
  • amount
    stringrequired
  • currency
    string
  • bank_account_id
    integer
  • posting_date
    string (date)required
  • method
    string
  • reference
    string | null
  • memo
    string | null
  • status
    stringrequired
    One of: draft, posted, cancelled, reversed.
  • prepared_by_id
    integer
  • approved_by_id
    integer | null
  • approved_at
    string | null (date-time)
  • journal_entry_id
    integer | null
  • reason
    string | null
  • reversal_entry_id
    integer | null
  • reversal_date
    string | null (date)

Errors

  • 400Malformed JSON request body
  • 401Authentication required
  • 403Scope or separation of duties denied
  • 404Scoped source not found
  • 409State, revision, overapplication or idempotency conflict
  • 422Invalid data, dates, account or closed period

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/refunds/1/transition" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "action": "post"
}'

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