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.
- GET
/rest/v1.0/companies/{company_id}/accounting/ar/collections/disputesDisputes - POST
/rest/v1.0/companies/{company_id}/accounting/ar/collections/disputesOpen a dispute on a posted invoice (arEnter) - GET
/rest/v1.0/companies/{company_id}/accounting/ar/collections/disputes/{id}A dispute - POST
/rest/v1.0/companies/{company_id}/accounting/ar/collections/disputes/{id}/resolveResolve or withdraw a dispute (arEnter) - GET
/rest/v1.0/companies/{company_id}/accounting/ar/collections/paymentsOnline payments - GET
/rest/v1.0/companies/{company_id}/accounting/ar/collections/payments/{id}An online payment - GET
/rest/v1.0/companies/{company_id}/accounting/ar/collections/policiesDunning policies - POST
/rest/v1.0/companies/{company_id}/accounting/ar/collections/policiesCreate a dunning policy (arApprove) - PATCH
/rest/v1.0/companies/{company_id}/accounting/ar/collections/policies/{id}Replace a dunning policy's cadence (arApprove) - GET
/rest/v1.0/companies/{company_id}/accounting/ar/collections/portal_accessCustomer portal billing links - POST
/rest/v1.0/companies/{company_id}/accounting/ar/collections/portal_accessLink a customer portal grant to an AR customer (arApprove) - POST
/rest/v1.0/companies/{company_id}/accounting/ar/collections/portal_access/{id}/revokeRevoke a billing link (arApprove) - GET
/rest/v1.0/companies/{company_id}/accounting/ar/collections/promisesPromises to pay - POST
/rest/v1.0/companies/{company_id}/accounting/ar/collections/promisesRecord a promise to pay (arEnter) - POST
/rest/v1.0/companies/{company_id}/accounting/ar/collections/promises/{id}/cancelCancel an open promise (arEnter) - POST
/rest/v1.0/companies/{company_id}/accounting/ar/collections/runRun collections now (arEnter) - GET
/rest/v1.0/companies/{company_id}/accounting/ar/collections/settingsCollections and online payment settings - PATCH
/rest/v1.0/companies/{company_id}/accounting/ar/collections/settingsUpdate collections settings (arApprove) - GET
/rest/v1.0/companies/{company_id}/accounting/ar/collections/worklistPrioritized collections worklist - GET
/rest/v1.0/companies/{company_id}/accounting/ar/customersList AR customers - GET
/rest/v1.0/companies/{company_id}/accounting/ar/customers/{id}Customer open balances net of posted receipts and reversals; paginated invoice history - GET
/rest/v1.0/companies/{company_id}/accounting/ar/customers/{id}/collection_notesLatest 100 collection notes for the customer in permitted entities. - POST
/rest/v1.0/companies/{company_id}/accounting/ar/customers/{id}/collection_notesAdd a collection note (optional invoice and promise to pay). arEnter. - GET
/rest/v1.0/companies/{company_id}/accounting/ar/customers/{id}/collectionsA customer's collections view - PATCH
/rest/v1.0/companies/{company_id}/accounting/ar/customers/{id}/collectionsUpdate a customer's collections profile (arEnter) - 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. - 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. - GET
/rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}Get a GMP application - PATCH
/rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}Edit a GMP application - POST
/rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/billBill a GMP application - POST
/rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/certifyCertify a GMP application - GET
/rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/packageGMP application owner package - GET
/rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/registerGMP application cost register - POST
/rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/returnReturn a GMP application - POST
/rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/submitSubmit a GMP application - POST
/rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/voidVoid a GMP application - POST
/rest/v1.0/companies/{company_id}/accounting/ar/gmp_applications/{id}/withdrawWithdraw a GMP certification - POST
/rest/v1.0/companies/{company_id}/accounting/ar/gmp_draws/{id}/decisionDecide a GMP draw - GET
/rest/v1.0/companies/{company_id}/accounting/ar/gmp/statusGMP status of a project - GET
/rest/v1.0/companies/{company_id}/accounting/ar/invoicesList scoped invoices (default 100, maximum 100 per page) - 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 - GET
/rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}Get scoped invoice - PATCH
/rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}Replace current draft revision; all editors are excluded from approval - GET
/rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/attachmentsList attachments on a AR invoice - POST
/rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/attachmentsAttach a file to a AR invoice - 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. - 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. - GET
/rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/pdfInvoice PDF - 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. - 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. - POST
/rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/transitionSubmit, return to draft, independently approve, or post an invoice - POST
/rest/v1.0/companies/{company_id}/accounting/ar/invoices/from_billingDraft an AR invoice from a non-progress billing - POST
/rest/v1.0/companies/{company_id}/accounting/ar/invoices/from_payment_applicationBill a certified owner pay app in AR (once per pay app) - GET
/rest/v1.0/companies/{company_id}/accounting/ar/payment_applications/{id}/pdfG702/G703 PDF of a certified owner pay app - PUT
/rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/billing_methodSet a prime contract's billing method - GET
/rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/billing_termsGet a prime contract's billing terms - PUT
/rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/billing_termsPropose a prime contract's billing terms - POST
/rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/billing_terms/approveApprove a prime contract's proposed billing terms - GET
/rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/closeoutGet a prime contract's closeout documents - PUT
/rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/closeoutSet a prime contract's closeout documents - GET
/rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/gmp_applicationsList a GMP contract's applications - POST
/rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/gmp_applicationsStart a GMP application - GET
/rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/gmp_closeoutGMP close-out reconciliation - GET
/rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/gmp_drawsList GMP contingency and allowance draws - POST
/rest/v1.0/companies/{company_id}/accounting/ar/prime_contracts/{id}/gmp_drawsPropose a GMP contingency or allowance draw - GET
/rest/v1.0/companies/{company_id}/accounting/ar/receiptsReceipt history, 50 per page - POST
/rest/v1.0/companies/{company_id}/accounting/ar/receiptsRecord a fully allocated draft; matching request-key retries return the original receipt - GET
/rest/v1.0/companies/{company_id}/accounting/ar/receipts/{id}Receipt detail and immutable applications - 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. - GET
/rest/v1.0/companies/{company_id}/accounting/ar/receipts/{id}/attachmentsList attachments on a AR receipt - POST
/rest/v1.0/companies/{company_id}/accounting/ar/receipts/{id}/attachmentsAttach a file to a AR receipt - 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. - POST
/rest/v1.0/companies/{company_id}/accounting/ar/receipts/{id}/transitionIndependently approve or post; balances are revalidated under the company lock - 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 - GET
/rest/v1.0/companies/{company_id}/accounting/ar/refundsCustomer refunds, newest first (paginated). - 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. - GET
/rest/v1.0/companies/{company_id}/accounting/ar/refunds/{id}Refund detail. - 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/disputesDisputes
Disputes in permitted entities, newest first; filter by status and customer_id. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequired
- statusstringqueryOne of: open, resolved, withdrawn.
- customer_idintegerquery
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- idintegerrequired
- entity_idintegerrequired
- customer_idintegerrequired
- invoice_idintegerrequired
- reason_codestringrequiredOne of: pricing, quantity, quality, not_received, duplicate, retainage, change_order, documentation, other.
- amountstringrequired
- descriptionstring | nullrequired
- statusstringrequiredOne of: open, resolved, withdrawn.
- sourcestringrequiredOne of: staff, portal.
- raised_by_idinteger | nullrequired
- resolutionstring | nullrequired
- resolved_by_idinteger | nullrequired
- resolved_atstring (date-time) | nullrequired
- created_atstring (date-time)required
- days_openinteger | nullrequired
Errors
401Authentication required403Scope or permission denied404Not found in the caller's scope422Invalid query parameter
Example request
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/disputesOpen 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.
Parameters
- company_idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- request_keystring (uuid)required
- disputeobjectrequired
- dispute.invoice_idintegerrequired
- dispute.reason_codestringrequiredOne of: pricing, quantity, quality, not_received, duplicate, retainage, change_order, documentation, other.
- dispute.amountstringrequired
- dispute.descriptionstring | null
Response · 201 · object
- idintegerrequired
- entity_idintegerrequired
- customer_idintegerrequired
- invoice_idintegerrequired
- reason_codestringrequiredOne of: pricing, quantity, quality, not_received, duplicate, retainage, change_order, documentation, other.
- amountstringrequired
- descriptionstring | nullrequired
- statusstringrequiredOne of: open, resolved, withdrawn.
- sourcestringrequiredOne of: staff, portal.
- raised_by_idinteger | nullrequired
- resolutionstring | nullrequired
- resolved_by_idinteger | nullrequired
- resolved_atstring (date-time) | nullrequired
- created_atstring (date-time)required
- days_openinteger | nullrequired
Errors
400Malformed JSON request body401Authentication required403Scope or permission denied404Not found in the caller's scope409Conflict (state changed, duplicate or request key reuse)422Validation failed
Example request
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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- entity_idintegerrequired
- customer_idintegerrequired
- invoice_idintegerrequired
- reason_codestringrequiredOne of: pricing, quantity, quality, not_received, duplicate, retainage, change_order, documentation, other.
- amountstringrequired
- descriptionstring | nullrequired
- statusstringrequiredOne of: open, resolved, withdrawn.
- sourcestringrequiredOne of: staff, portal.
- raised_by_idinteger | nullrequired
- resolutionstring | nullrequired
- resolved_by_idinteger | nullrequired
- resolved_atstring (date-time) | nullrequired
- created_atstring (date-time)required
- days_openinteger | nullrequired
Errors
401Authentication required403Scope or permission denied404Not found in the caller's scope422Invalid query parameter
Example request
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}/resolveResolve or withdraw a dispute (arEnter)
Closing the last open dispute on an invoice clears its disputed flag. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- actionstringrequiredOne of: resolve, withdraw.
- resolutionstringrequired
Response · 200 · object
- idintegerrequired
- entity_idintegerrequired
- customer_idintegerrequired
- invoice_idintegerrequired
- reason_codestringrequiredOne of: pricing, quantity, quality, not_received, duplicate, retainage, change_order, documentation, other.
- amountstringrequired
- descriptionstring | nullrequired
- statusstringrequiredOne of: open, resolved, withdrawn.
- sourcestringrequiredOne of: staff, portal.
- raised_by_idinteger | nullrequired
- resolutionstring | nullrequired
- resolved_by_idinteger | nullrequired
- resolved_atstring (date-time) | nullrequired
- created_atstring (date-time)required
- days_openinteger | nullrequired
Errors
400Malformed JSON request body401Authentication required403Scope or permission denied404Not found in the caller's scope409Conflict (state changed, duplicate or request key reuse)422Validation failed
Example request
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/paymentsOnline 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.
Parameters
- company_idintegerpathrequired
- statusstringqueryOne of: pending, succeeded, failed, settled, held.
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- idintegerrequired
- entity_idintegerrequired
- customer_idintegerrequired
- providerstringrequired
- provider_refstringrequired
- methodstringrequiredOne of: ach, card.
- currencystringrequired
- amountstringrequired
- surchargestringrequired
- convenience_feestringrequired
- total_chargedstringrequired
- processor_feestringrequired
- statusstringrequiredOne of: pending, succeeded, failed, settled, held.
- receipt_idinteger | nullrequired
- payout_idinteger | nullrequired
- failure_reasonstring | nullrequired
- invoice_idsinteger[]required
- confirmed_atstring (date-time) | nullrequired
- settled_atstring (date-time) | nullrequired
- created_atstring (date-time)required
Errors
401Authentication required403Scope or permission denied404Not found in the caller's scope422Invalid query parameter
Example request
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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- entity_idintegerrequired
- customer_idintegerrequired
- providerstringrequired
- provider_refstringrequired
- methodstringrequiredOne of: ach, card.
- currencystringrequired
- amountstringrequired
- surchargestringrequired
- convenience_feestringrequired
- total_chargedstringrequired
- processor_feestringrequired
- statusstringrequiredOne of: pending, succeeded, failed, settled, held.
- receipt_idinteger | nullrequired
- payout_idinteger | nullrequired
- failure_reasonstring | nullrequired
- invoice_idsinteger[]required
- confirmed_atstring (date-time) | nullrequired
- settled_atstring (date-time) | nullrequired
- created_atstring (date-time)required
Errors
401Authentication required403Scope or permission denied404Not found in the caller's scope422Invalid query parameter
Example request
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/policiesDunning policies
One reminder cadence per customer class, with steps relative to the due date. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequired
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- idintegerrequired
- customer_classstringrequired
- namestringrequired
- is_activebooleanrequired
- escalation_user_idinteger | nullrequired
- revisionintegerrequired
- stepsobject[]required
- steps[].idintegerrequired
- steps[].offset_daysintegerrequired
- steps[].channelstringrequired
- steps[].subjectstringrequired
- steps[].bodystringrequired
- steps[].escalatebooleanrequired
- steps[].is_activebooleanrequired
Errors
401Authentication required403Scope or permission denied404Not found in the caller's scope422Invalid query parameter
Example request
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/policiesCreate 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.
Parameters
- company_idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- policyobjectrequired
- policy.customer_classstringrequired
- policy.namestringrequired
- policy.is_activeboolean
- policy.escalation_user_idinteger | null
- policy.stepsobject[]required
- policy.steps[].offset_daysintegerrequired
- policy.steps[].subjectstringrequired
- policy.steps[].bodystringrequired
- policy.steps[].escalateboolean
- policy.steps[].channelstring
Response · 201 · object
- idintegerrequired
- customer_classstringrequired
- namestringrequired
- is_activebooleanrequired
- escalation_user_idinteger | nullrequired
- revisionintegerrequired
- stepsobject[]required
- steps[].idintegerrequired
- steps[].offset_daysintegerrequired
- steps[].channelstringrequired
- steps[].subjectstringrequired
- steps[].bodystringrequired
- steps[].escalatebooleanrequired
- steps[].is_activebooleanrequired
Errors
400Malformed JSON request body401Authentication required403Scope or permission denied404Not found in the caller's scope409Conflict (state changed, duplicate or request key reuse)422Validation failed
Example request
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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- policyobjectrequired
- policy.customer_classstringrequired
- policy.namestringrequired
- policy.is_activeboolean
- policy.escalation_user_idinteger | null
- policy.stepsobject[]required
- policy.steps[].offset_daysintegerrequired
- policy.steps[].subjectstringrequired
- policy.steps[].bodystringrequired
- policy.steps[].escalateboolean
- policy.steps[].channelstring
Response · 200 · object
- idintegerrequired
- customer_classstringrequired
- namestringrequired
- is_activebooleanrequired
- escalation_user_idinteger | nullrequired
- revisionintegerrequired
- stepsobject[]required
- steps[].idintegerrequired
- steps[].offset_daysintegerrequired
- steps[].channelstringrequired
- steps[].subjectstringrequired
- steps[].bodystringrequired
- steps[].escalatebooleanrequired
- steps[].is_activebooleanrequired
Errors
400Malformed JSON request body401Authentication required403Scope or permission denied404Not found in the caller's scope409Conflict (state changed, duplicate or request key reuse)422Validation failed
Example request
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_accessCustomer portal billing links
Links from customer portal grants to AR customers. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequired
- customer_idintegerquery
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- idintegerrequired
- grant_idintegerrequired
- customer_idintegerrequired
- allow_paymentsbooleanrequired
- activebooleanrequired
- created_by_idintegerrequired
- created_atstring (date-time)required
- revoked_atstring (date-time) | nullrequired
- revoked_by_idinteger | nullrequired
Errors
401Authentication required403Scope or permission denied404Not found in the caller's scope422Invalid query parameter
Example request
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_accessLink 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.
Parameters
- company_idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- request_keystring (uuid)
- portal_accessobjectrequired
- portal_access.grant_idintegerrequired
- portal_access.customer_idintegerrequired
- portal_access.allow_paymentsboolean
Response · 201 · object
- idintegerrequired
- grant_idintegerrequired
- customer_idintegerrequired
- allow_paymentsbooleanrequired
- activebooleanrequired
- created_by_idintegerrequired
- created_atstring (date-time)required
- revoked_atstring (date-time) | nullrequired
- revoked_by_idinteger | nullrequired
Errors
400Malformed JSON request body401Authentication required403Scope or permission denied404Not found in the caller's scope409Conflict (state changed, duplicate or request key reuse)422Validation failed
Example request
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}/revokeRevoke a billing link (arApprove)
The portal stops showing billing for the grant at once. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- reasonstringrequired
Response · 200 · object
- idintegerrequired
- grant_idintegerrequired
- customer_idintegerrequired
- allow_paymentsbooleanrequired
- activebooleanrequired
- created_by_idintegerrequired
- created_atstring (date-time)required
- revoked_atstring (date-time) | nullrequired
- revoked_by_idinteger | nullrequired
Errors
400Malformed JSON request body401Authentication required403Scope or permission denied404Not found in the caller's scope409Conflict (state changed, duplicate or request key reuse)422Validation failed
Example request
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/promisesPromises 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.
Parameters
- company_idintegerpathrequired
- statusstringqueryOne of: open, kept, broken, cancelled.
- customer_idintegerquery
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- idintegerrequired
- entity_idintegerrequired
- customer_idintegerrequired
- invoice_idsinteger[]required
- start_datestring (date)required
- promised_datestring (date)required
- amountstringrequired
- received_amountstringrequired
- statusstringrequiredOne of: open, kept, broken, cancelled.
- sourcestringrequiredOne of: staff, portal.
- notestring | nullrequired
- created_by_idinteger | nullrequired
- resolved_datestring (date) | nullrequired
- created_atstring (date-time)required
Errors
401Authentication required403Scope or permission denied404Not found in the caller's scope422Invalid query parameter
Example request
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/promisesRecord 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.
Parameters
- company_idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- request_keystring (uuid)required
- promiseobjectrequired
- promise.entity_idintegerrequired
- promise.customer_idintegerrequired
- promise.invoice_idsinteger[]
- promise.promised_datestring (date)required
- promise.amountstringrequired
- promise.notestring | null
Response · 201 · object
- idintegerrequired
- entity_idintegerrequired
- customer_idintegerrequired
- invoice_idsinteger[]required
- start_datestring (date)required
- promised_datestring (date)required
- amountstringrequired
- received_amountstringrequired
- statusstringrequiredOne of: open, kept, broken, cancelled.
- sourcestringrequiredOne of: staff, portal.
- notestring | nullrequired
- created_by_idinteger | nullrequired
- resolved_datestring (date) | nullrequired
- created_atstring (date-time)required
Errors
400Malformed JSON request body401Authentication required403Scope or permission denied404Not found in the caller's scope409Conflict (state changed, duplicate or request key reuse)422Validation failed
Example request
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}/cancelCancel an open promise (arEnter)
A cancelled promise no longer pauses dunning and is left out of the kept rate. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- reasonstringrequired
Response · 200 · object
- idintegerrequired
- entity_idintegerrequired
- customer_idintegerrequired
- invoice_idsinteger[]required
- start_datestring (date)required
- promised_datestring (date)required
- amountstringrequired
- received_amountstringrequired
- statusstringrequiredOne of: open, kept, broken, cancelled.
- sourcestringrequiredOne of: staff, portal.
- notestring | nullrequired
- created_by_idinteger | nullrequired
- resolved_datestring (date) | nullrequired
- created_atstring (date-time)required
Errors
400Malformed JSON request body401Authentication required403Scope or permission denied404Not found in the caller's scope409Conflict (state changed, duplicate or request key reuse)422Validation failed
Example request
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/runRun 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.
Parameters
- company_idintegerpathrequired
Response · 200 · object
- as_ofstring (date)required
- statusstringrequiredOne of: ran, disabled, not_business_day, quiet_hours, no_policy.
- resume_atstring (date-time) | nullrequired
- sentintegerrequired
- skippedintegerrequired
- failedintegerrequired
- suppressedintegerrequired
- pausedobjectrequired
- promisesobjectrequired
- promises.keptintegerrequired
- promises.brokenintegerrequired
Errors
400Malformed JSON request body401Authentication required403Scope or permission denied404Not found in the caller's scope409Conflict (state changed, duplicate or request key reuse)422Validation failed
Example request
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/settingsCollections 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.
Parameters
- company_idintegerpathrequired
Response · 200 · object
- revisionintegerrequired
- dunning_enabledbooleanrequired
- quiet_startstringrequired
- quiet_endstringrequired
- business_daysinteger[]required
- holidaysstring (date)[]required
- promise_grace_daysintegerrequired
- portal_payments_enabledbooleanrequired
- providerstringrequired
- ach_enabledbooleanrequired
- card_enabledbooleanrequired
- clearing_account_idinteger | nullrequired
- payout_account_idinteger | nullrequired
- fee_account_idinteger | nullrequired
- surcharge_enabledbooleanrequired
- surcharge_pctstringrequired
- convenience_fee_enabledbooleanrequired
- convenience_feestringrequired
- fee_income_account_idinteger | nullrequired
Errors
401Authentication required403Scope or permission denied404Not found in the caller's scope422Invalid query parameter
Example request
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/settingsUpdate 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.
Parameters
- company_idintegerpathrequired
Request body
- revisioninteger
- settingsobjectrequired
- settings.dunning_enabledboolean
- settings.quiet_startstring
- settings.quiet_endstring
- settings.business_daysinteger[]
- settings.holidaysstring (date)[]
- settings.promise_grace_daysinteger
- settings.portal_payments_enabledboolean
- settings.ach_enabledboolean
- settings.card_enabledboolean
- settings.clearing_account_idinteger | null
- settings.payout_account_idinteger | null
- settings.fee_account_idinteger | null
- settings.surcharge_enabledboolean
- settings.surcharge_pctstring
- settings.convenience_fee_enabledboolean
- settings.convenience_feestring
- settings.fee_income_account_idinteger | null
Response · 200 · object
- revisionintegerrequired
- dunning_enabledbooleanrequired
- quiet_startstringrequired
- quiet_endstringrequired
- business_daysinteger[]required
- holidaysstring (date)[]required
- promise_grace_daysintegerrequired
- portal_payments_enabledbooleanrequired
- providerstringrequired
- ach_enabledbooleanrequired
- card_enabledbooleanrequired
- clearing_account_idinteger | nullrequired
- payout_account_idinteger | nullrequired
- fee_account_idinteger | nullrequired
- surcharge_enabledbooleanrequired
- surcharge_pctstringrequired
- convenience_fee_enabledbooleanrequired
- convenience_feestringrequired
- fee_income_account_idinteger | nullrequired
Errors
400Malformed JSON request body401Authentication required403Scope or permission denied404Not found in the caller's scope409Conflict (state changed, duplicate or request key reuse)422Validation failed
Example request
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/worklistPrioritized 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.
Parameters
- company_idintegerpathrequired
- as_ofstring (date)query
- collector_idintegerquery
- entity_idintegerquery
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- customer_idintegerrequired
- customer_namestringrequired
- customer_classstringrequired
- collector_user_idinteger | nullrequired
- on_holdbooleanrequired
- follow_up_datestring (date) | nullrequired
- open_currentstringrequired
- past_duestringrequired
- oldest_days_past_dueintegerrequired
- disputed_amountstringrequired
- open_disputesintegerrequired
- open_promiseobject | nullrequired
- open_promise.idintegerrequired
- open_promise.promised_datestring (date)required
- open_promise.amountstringrequired
- broken_promisesintegerrequired
- days_to_paystring | nullrequired
- terms_daysintegerrequired
- scorestringrequired
- riskstringrequired
- last_activity_atstring (date-time) | nullrequired
Errors
401Authentication required403Scope or permission denied404Not found in the caller's scope422Invalid query parameter
Example request
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/customersList 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.
Parameters
- company_idintegerpathrequired
- searchstringquery
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- idintegerrequired
- namestringrequired
- has_profilebooleanrequired
- term_idinteger | nullrequired
Errors
401Authentication required403Tenant, permission or entity access denied
Example request
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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- pageintegerquery
Response · 200 · object
- customerobjectrequired
- customer.idintegerrequired
- customer.namestringrequired
- balancesobject[]required
- balances[].currencystringrequired
- balances[].currentstringrequired
- balances[].retainagestringrequired
- totalintegerrequired
- invoicesobject[]required
- invoices[].entity_idintegerrequired
- invoices[].customer_idintegerrequired
- invoices[].source_referencestringrequired
- invoices[].invoice_datestring (date)required
- invoices[].posting_datestring (date)required
- invoices[].due_datestring (date)required
- invoices[].memostring | nullrequired
- invoices[].linesobject[]required
- invoices[].idintegerrequired
- invoices[].numberstringrequired
- invoices[].source_typestringrequired
- invoices[].source_idintegerrequired
- invoices[].source_revisionintegerrequired
- invoices[].revisionintegerrequired
- invoices[].statusstringrequiredOne of: draft, pending_approval, approved, posted, reversed, cancelled.
- invoices[].currencystringrequired
- invoices[].totalstringrequired
- invoices[].retainage_amountstringrequired
- invoices[].current_amountstringrequired
- invoices[].open_currentstringrequired
- invoices[].open_retainagestringrequired
- invoices[].prepared_by_idintegerrequired
- invoices[].approved_by_idinteger | nullrequired
- invoices[].approved_atstring (date-time) | nullrequired
- invoices[].journal_entry_idinteger | nullrequired
- invoices[].paid_currentstringrequired
- invoices[].paid_retainagestringrequired
- invoices[].corrects_invoice_idinteger | nullrequired
- invoices[].reversalobject | nullrequired
- invoices[].applicationsobject[]required
- invoices[].kindstringrequiredOne of: standard, retainage_release, credit_memo.
- invoices[].payment_application_idinteger | nullrequiredOwner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
- invoices[].prime_contract_idinteger | nullrequired
- invoices[].project_idinteger | nullrequired
- invoices[].released_retainagestringrequiredRetainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
- invoices[].tax_amountstringrequired
- invoices[].disputedbooleanrequired
- invoices[].dispute_reasonstring | nullrequired
- invoices[].credited_currentstringrequiredCurrent AR settled by credit memos, including any sales tax they reverse.
- invoices[].credit_reasonstring | nullrequiredCredit memos only. One of: return, write_off, discount, tax_adjustment, null.
- invoices[].cancellation_reasonstring | nullrequired
- invoices[].tax_override_reasonstring | nullrequired
- invoices[].tax_warningsstring[]requiredSales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
- invoices[].on_account_amountstring | nullCredit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
- invoices[].available_creditstring | nullPosted, unreversed credit memos: on-account amount less applications and posted refunds.
- invoices[].credit_applicationsobject[]On-account credit memos applied to this invoice (while each stands).
- invoices[].outside_contract_reasonstring | nullrequired
- profileobject | null
- profile.is_customerboolean
- profile.term_idinteger | null
- profile.term_codestring | null
- profile.due_daysinteger | null
- profile.credit_limitstring | null
- profile.billing_contact_namestring | null
- profile.billing_emailstring | null
- profile.billing_addressstring | null
Errors
401Authentication required403Tenant, permission or entity access denied404Scoped record not found409State, revision, duplicate source or request conflict422Invalid input, references, configuration or posting period
Example request
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_notesLatest 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- kindstringOne of: note, call, email.
- follow_up_datestring (date) | null
- idinteger
- entity_idinteger
- customer_idinteger
- invoice_idinteger | null
- notestring
- promise_datestring (date) | null
- promise_amountstring | null
- created_by_idinteger
- created_atstring (date-time)
Errors
401Authentication required403Scope or separation of duties denied404Scoped source not found
Example request
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_notesAdd 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- kindstringOne of: note, call, email.
- follow_up_datestring (date) | null
- entity_idintegerrequired
- invoice_idinteger | null
- notestringrequired
- promise_datestring (date) | null
- promise_amountstring | null
Response · 201 · object
- kindstringOne of: note, call, email.
- follow_up_datestring (date) | null
- idinteger
- entity_idinteger
- customer_idinteger
- invoice_idinteger | null
- notestring
- promise_datestring (date) | null
- promise_amountstring | null
- created_by_idinteger
- created_atstring (date-time)
Errors
400Malformed JSON request body401Authentication required403Scope or separation of duties denied404Scoped source not found409State, revision, overapplication or idempotency conflict422Invalid data, dates, account or closed period
Example request
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}/collectionsA 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- customerobjectrequired
- customer.idintegerrequired
- customer.namestringrequired
- as_ofstring (date)required
- profileobjectrequired
- profile.customer_idintegerrequired
- profile.customer_classstringrequired
- profile.collector_user_idinteger | nullrequired
- profile.on_holdbooleanrequired
- profile.hold_reasonstring | nullrequired
- profile.follow_up_datestring (date) | nullrequired
- days_to_paystring | nullrequired
- disputesobject[]required
- disputes[].idintegerrequired
- disputes[].entity_idintegerrequired
- disputes[].customer_idintegerrequired
- disputes[].invoice_idintegerrequired
- disputes[].reason_codestringrequiredOne of: pricing, quantity, quality, not_received, duplicate, retainage, change_order, documentation, other.
- disputes[].amountstringrequired
- disputes[].descriptionstring | nullrequired
- disputes[].statusstringrequiredOne of: open, resolved, withdrawn.
- disputes[].sourcestringrequiredOne of: staff, portal.
- disputes[].raised_by_idinteger | nullrequired
- disputes[].resolutionstring | nullrequired
- disputes[].resolved_by_idinteger | nullrequired
- disputes[].resolved_atstring (date-time) | nullrequired
- disputes[].created_atstring (date-time)required
- disputes[].days_openinteger | nullrequired
- promisesobject[]required
- promises[].idintegerrequired
- promises[].entity_idintegerrequired
- promises[].customer_idintegerrequired
- promises[].invoice_idsinteger[]required
- promises[].start_datestring (date)required
- promises[].promised_datestring (date)required
- promises[].amountstringrequired
- promises[].received_amountstringrequired
- promises[].statusstringrequiredOne of: open, kept, broken, cancelled.
- promises[].sourcestringrequiredOne of: staff, portal.
- promises[].notestring | nullrequired
- promises[].created_by_idinteger | nullrequired
- promises[].resolved_datestring (date) | nullrequired
- promises[].created_atstring (date-time)required
- dunning_sendsobject[]required
- dunning_sends[].idintegerrequired
- dunning_sends[].entity_idintegerrequired
- dunning_sends[].customer_idintegerrequired
- dunning_sends[].invoice_idintegerrequired
- dunning_sends[].step_idintegerrequired
- dunning_sends[].offset_daysintegerrequired
- dunning_sends[].scheduled_datestring (date)required
- dunning_sends[].run_datestring (date)required
- dunning_sends[].statusstringrequiredOne of: sent, skipped, failed.
- dunning_sends[].reasonstring | nullrequired
- dunning_sends[].escalated_to_user_idinteger | nullrequired
- dunning_sends[].created_atstring (date-time)required
Errors
401Authentication required403Scope or permission denied404Not found in the caller's scope422Invalid query parameter
Example request
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}/collectionsUpdate 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- profileobjectrequired
- profile.customer_classstring
- profile.collector_user_idinteger | null
- profile.on_holdboolean
- profile.hold_reasonstring | null
- profile.follow_up_datestring (date) | null
Response · 200 · object
- customerobjectrequired
- customer.idintegerrequired
- customer.namestringrequired
- as_ofstring (date)required
- profileobjectrequired
- profile.customer_idintegerrequired
- profile.customer_classstringrequired
- profile.collector_user_idinteger | nullrequired
- profile.on_holdbooleanrequired
- profile.hold_reasonstring | nullrequired
- profile.follow_up_datestring (date) | nullrequired
- days_to_paystring | nullrequired
- disputesobject[]required
- disputes[].idintegerrequired
- disputes[].entity_idintegerrequired
- disputes[].customer_idintegerrequired
- disputes[].invoice_idintegerrequired
- disputes[].reason_codestringrequiredOne of: pricing, quantity, quality, not_received, duplicate, retainage, change_order, documentation, other.
- disputes[].amountstringrequired
- disputes[].descriptionstring | nullrequired
- disputes[].statusstringrequiredOne of: open, resolved, withdrawn.
- disputes[].sourcestringrequiredOne of: staff, portal.
- disputes[].raised_by_idinteger | nullrequired
- disputes[].resolutionstring | nullrequired
- disputes[].resolved_by_idinteger | nullrequired
- disputes[].resolved_atstring (date-time) | nullrequired
- disputes[].created_atstring (date-time)required
- disputes[].days_openinteger | nullrequired
- promisesobject[]required
- promises[].idintegerrequired
- promises[].entity_idintegerrequired
- promises[].customer_idintegerrequired
- promises[].invoice_idsinteger[]required
- promises[].start_datestring (date)required
- promises[].promised_datestring (date)required
- promises[].amountstringrequired
- promises[].received_amountstringrequired
- promises[].statusstringrequiredOne of: open, kept, broken, cancelled.
- promises[].sourcestringrequiredOne of: staff, portal.
- promises[].notestring | nullrequired
- promises[].created_by_idinteger | nullrequired
- promises[].resolved_datestring (date) | nullrequired
- promises[].created_atstring (date-time)required
- dunning_sendsobject[]required
- dunning_sends[].idintegerrequired
- dunning_sends[].entity_idintegerrequired
- dunning_sends[].customer_idintegerrequired
- dunning_sends[].invoice_idintegerrequired
- dunning_sends[].step_idintegerrequired
- dunning_sends[].offset_daysintegerrequired
- dunning_sends[].scheduled_datestring (date)required
- dunning_sends[].run_datestring (date)required
- dunning_sends[].statusstringrequiredOne of: sent, skipped, failed.
- dunning_sends[].reasonstring | nullrequired
- dunning_sends[].escalated_to_user_idinteger | nullrequired
- dunning_sends[].created_atstring (date-time)required
Errors
400Malformed JSON request body401Authentication required403Scope or permission denied404Not found in the caller's scope409Conflict (state changed, duplicate or request key reuse)422Validation failed
Example request
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}/statementCustomer 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- as_ofstring (date)queryStatement date (default today): as-of open amounts, receipts and applications dated on or before it.
Response · 200 · object
- customerobject
- customer.idintegerrequired
- customer.namestringrequired
- profileobject | nullNull for an entity-restricted grant whose entities have no AR activity with the customer.
- profile.is_customerboolean
- profile.term_idinteger | null
- profile.term_codestring | null
- profile.due_daysinteger | null
- profile.credit_limitstring | null
- profile.billing_contact_namestring | null
- profile.billing_emailstring | null
- profile.billing_addressstring | null
- as_ofstring (date)
- invoicesobject[]
- invoices[].entity_idintegerrequired
- invoices[].customer_idintegerrequired
- invoices[].source_referencestringrequired
- invoices[].invoice_datestring (date)required
- invoices[].posting_datestring (date)required
- invoices[].due_datestring (date)required
- invoices[].memostring | nullrequired
- invoices[].linesobject[]required
- invoices[].idintegerrequired
- invoices[].numberstringrequired
- invoices[].source_typestringrequired
- invoices[].source_idintegerrequired
- invoices[].source_revisionintegerrequired
- invoices[].revisionintegerrequired
- invoices[].statusstringrequiredOne of: draft, pending_approval, approved, posted, reversed, cancelled.
- invoices[].currencystringrequired
- invoices[].totalstringrequired
- invoices[].retainage_amountstringrequired
- invoices[].current_amountstringrequired
- invoices[].open_currentstringrequired
- invoices[].open_retainagestringrequired
- invoices[].prepared_by_idintegerrequired
- invoices[].approved_by_idinteger | nullrequired
- invoices[].approved_atstring (date-time) | nullrequired
- invoices[].journal_entry_idinteger | nullrequired
- invoices[].paid_currentstringrequired
- invoices[].paid_retainagestringrequired
- invoices[].corrects_invoice_idinteger | nullrequired
- invoices[].reversalobject | nullrequired
- invoices[].applicationsobject[]required
- invoices[].kindstringrequiredOne of: standard, retainage_release, credit_memo.
- invoices[].payment_application_idinteger | nullrequiredOwner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
- invoices[].prime_contract_idinteger | nullrequired
- invoices[].project_idinteger | nullrequired
- invoices[].released_retainagestringrequiredRetainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
- invoices[].tax_amountstringrequired
- invoices[].disputedbooleanrequired
- invoices[].dispute_reasonstring | nullrequired
- invoices[].credited_currentstringrequiredCurrent AR settled by credit memos, including any sales tax they reverse.
- invoices[].credit_reasonstring | nullrequiredCredit memos only. One of: return, write_off, discount, tax_adjustment, null.
- invoices[].cancellation_reasonstring | nullrequired
- invoices[].tax_override_reasonstring | nullrequired
- invoices[].tax_warningsstring[]requiredSales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
- invoices[].on_account_amountstring | nullCredit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
- invoices[].available_creditstring | nullPosted, unreversed credit memos: on-account amount less applications and posted refunds.
- invoices[].credit_applicationsobject[]On-account credit memos applied to this invoice (while each stands).
- invoices[].outside_contract_reasonstring | nullrequired
- open_totalstringopen_current plus retainage_not_due.
- unapplied_cashstring
- balance_duestringopen_current less unapplied cash; unreleased retainage is not due.
- open_currentstringOpen current AR as of the date, net of owner-direct payment credits.
- retainage_not_duestringUnreleased retainage held as of the date; shown, not due.
- owner_direct_creditsstringOwner-direct AP payments credited to this customer's AR, included in open_current.
- on_account_creditsstringOpen on-account credit memos as of the date (positive), netted in open_current.
Errors
401Authentication required403Scope or separation of duties denied404Scoped source not found
Example request
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/depositsDeposit 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.
Parameters
- company_idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- request_keystring (uuid)required
- entity_idintegerrequired
- bank_account_idintegerrequired
- posting_datestring (date)required
- receipt_idsinteger[]required
Response · 201 · object
- idinteger
- numberstring
- entity_idinteger
- bank_account_idinteger
- posting_datestring (date)
- currencystring
- totalstring
- journal_entry_idinteger
- receipt_idsinteger[]
Errors
400Malformed JSON request body401Authentication required403Scope or separation of duties denied404Scoped source not found409State, revision, overapplication or idempotency conflict422Invalid data, dates, account or closed period
Example request
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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- prime_contract_idintegerrequired
- project_idinteger
- entity_idinteger
- numberintegerrequired
- period_endstring (date)required
- finalboolean
- statusstringrequiredOne of: draft, submitted, returned, certified, billed, void.
- revisionintegerrequired
- exclusionsobjectDisallowed job cost entries: entry id -> reason.
- storedobject[]
- resultobject | nullThe 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_hashstring | null
- terms_revisioninteger | null
- earned_to_datestring
- retainage_to_datestring
- current_duestringrequired
- prepared_by_idinteger
- contributor_idsinteger[]
- submitted_atstring | null (date-time)
- returned_atstring | null (date-time)
- return_reasonstring | null
- certified_by_idinteger | null
- certified_atstring | null (date-time)
- reviewer_namestring | null
- reviewer_rolestring | null
- reviewer_datestring | null (date)
- certification_notestring | null
- invoice_idinteger | null
- billed_atstring | null (date-time)
- voided_atstring | null (date-time)
- void_reasonstring | null
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- revisionintegerrequired
- period_endstring (date)
- finalboolean
- exclusionsobject
- storedobject[]
- stored[].cost_code_idinteger | nullrequired
- stored[].descriptionstringrequired
- stored[].amountstringrequired
- stored[].referencestring | null
Response · 200 · object
- idintegerrequired
- prime_contract_idintegerrequired
- project_idinteger
- entity_idinteger
- numberintegerrequired
- period_endstring (date)required
- finalboolean
- statusstringrequiredOne of: draft, submitted, returned, certified, billed, void.
- revisionintegerrequired
- exclusionsobjectDisallowed job cost entries: entry id -> reason.
- storedobject[]
- resultobject | nullThe 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_hashstring | null
- terms_revisioninteger | null
- earned_to_datestring
- retainage_to_datestring
- current_duestringrequired
- prepared_by_idinteger
- contributor_idsinteger[]
- submitted_atstring | null (date-time)
- returned_atstring | null (date-time)
- return_reasonstring | null
- certified_by_idinteger | null
- certified_atstring | null (date-time)
- reviewer_namestring | null
- reviewer_rolestring | null
- reviewer_datestring | null (date)
- certification_notestring | null
- invoice_idinteger | null
- billed_atstring | null (date-time)
- voided_atstring | null (date-time)
- void_reasonstring | null
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Stale revision, wrong state, or the sources behind the application changed422Validation failed
Example request
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}/billBill 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- invoice_datestring (date)required
- posting_datestring (date)
- due_datestring (date)
- revenue_account_idinteger
Response · 201 · object
- applicationobjectrequired
- application.idintegerrequired
- application.prime_contract_idintegerrequired
- application.project_idinteger
- application.entity_idinteger
- application.numberintegerrequired
- application.period_endstring (date)required
- application.finalboolean
- application.statusstringrequiredOne of: draft, submitted, returned, certified, billed, void.
- application.revisionintegerrequired
- application.exclusionsobjectDisallowed job cost entries: entry id -> reason.
- application.storedobject[]
- application.resultobject | nullThe 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_hashstring | null
- application.terms_revisioninteger | null
- application.earned_to_datestring
- application.retainage_to_datestring
- application.current_duestringrequired
- application.prepared_by_idinteger
- application.contributor_idsinteger[]
- application.submitted_atstring | null (date-time)
- application.returned_atstring | null (date-time)
- application.return_reasonstring | null
- application.certified_by_idinteger | null
- application.certified_atstring | null (date-time)
- application.reviewer_namestring | null
- application.reviewer_rolestring | null
- application.reviewer_datestring | null (date)
- application.certification_notestring | null
- application.invoice_idinteger | null
- application.billed_atstring | null (date-time)
- application.voided_atstring | null (date-time)
- application.void_reasonstring | null
- application.created_atstring (date-time)
- application.updated_atstring (date-time)
- invoiceobjectrequired
- invoice.entity_idintegerrequired
- invoice.customer_idintegerrequired
- invoice.source_referencestringrequired
- invoice.invoice_datestring (date)required
- invoice.posting_datestring (date)required
- invoice.due_datestring (date)required
- invoice.memostring | nullrequired
- invoice.linesobject[]required
- invoice.idintegerrequired
- invoice.numberstringrequired
- invoice.source_typestringrequired
- invoice.source_idintegerrequired
- invoice.source_revisionintegerrequired
- invoice.revisionintegerrequired
- invoice.statusstringrequiredOne of: draft, pending_approval, approved, posted, reversed, cancelled.
- invoice.currencystringrequired
- invoice.totalstringrequired
- invoice.retainage_amountstringrequired
- invoice.current_amountstringrequired
- invoice.open_currentstringrequired
- invoice.open_retainagestringrequired
- invoice.prepared_by_idintegerrequired
- invoice.approved_by_idinteger | nullrequired
- invoice.approved_atstring (date-time) | nullrequired
- invoice.journal_entry_idinteger | nullrequired
- invoice.paid_currentstringrequired
- invoice.paid_retainagestringrequired
- invoice.corrects_invoice_idinteger | nullrequired
- invoice.reversalobject | nullrequired
- invoice.applicationsobject[]required
- invoice.kindstringrequiredOne of: standard, retainage_release, credit_memo.
- invoice.payment_application_idinteger | nullrequiredOwner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
- invoice.prime_contract_idinteger | nullrequired
- invoice.project_idinteger | nullrequired
- invoice.released_retainagestringrequiredRetainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
- invoice.tax_amountstringrequired
- invoice.disputedbooleanrequired
- invoice.dispute_reasonstring | nullrequired
- invoice.credited_currentstringrequiredCurrent AR settled by credit memos, including any sales tax they reverse.
- invoice.credit_reasonstring | nullrequiredCredit memos only. One of: return, write_off, discount, tax_adjustment, null.
- invoice.cancellation_reasonstring | nullrequired
- invoice.tax_override_reasonstring | nullrequired
- invoice.tax_warningsstring[]requiredSales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
- invoice.on_account_amountstring | nullCredit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
- invoice.available_creditstring | nullPosted, unreversed credit memos: on-account amount less applications and posted refunds.
- invoice.credit_applicationsobject[]On-account credit memos applied to this invoice (while each stands).
- invoice.outside_contract_reasonstring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Stale revision, wrong state, or the sources behind the application changed422Validation failed
Example request
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}/certifyCertify 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- revisionintegerrequired
- reviewer_namestringrequired
- reviewer_rolestringrequiredOne of: owner, architect, owner_representative, lender, other.
- reviewer_datestring (date)required
- certified_amountstringrequired
- notestring
Response · 200 · object
- idintegerrequired
- prime_contract_idintegerrequired
- project_idinteger
- entity_idinteger
- numberintegerrequired
- period_endstring (date)required
- finalboolean
- statusstringrequiredOne of: draft, submitted, returned, certified, billed, void.
- revisionintegerrequired
- exclusionsobjectDisallowed job cost entries: entry id -> reason.
- storedobject[]
- resultobject | nullThe 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_hashstring | null
- terms_revisioninteger | null
- earned_to_datestring
- retainage_to_datestring
- current_duestringrequired
- prepared_by_idinteger
- contributor_idsinteger[]
- submitted_atstring | null (date-time)
- returned_atstring | null (date-time)
- return_reasonstring | null
- certified_by_idinteger | null
- certified_atstring | null (date-time)
- reviewer_namestring | null
- reviewer_rolestring | null
- reviewer_datestring | null (date)
- certification_notestring | null
- invoice_idinteger | null
- billed_atstring | null (date-time)
- voided_atstring | null (date-time)
- void_reasonstring | null
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Stale revision, wrong state, or the sources behind the application changed422Validation failed
Example request
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}/packageGMP 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · string (binary)
No documented fields.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company
Example request
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}/registerGMP 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- scopestringqueryOne of: period, to_date.
- pageintegerquery
- per_pageintegerquery
- formatstringqueryOne of: json, csv.
Response · 200 · object
- totalintegerrequired
- pageinteger
- per_pageinteger
- rowsobject[]required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/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}/returnReturn 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- revisionintegerrequired
- reasonstringrequired
Response · 200 · object
- idintegerrequired
- prime_contract_idintegerrequired
- project_idinteger
- entity_idinteger
- numberintegerrequired
- period_endstring (date)required
- finalboolean
- statusstringrequiredOne of: draft, submitted, returned, certified, billed, void.
- revisionintegerrequired
- exclusionsobjectDisallowed job cost entries: entry id -> reason.
- storedobject[]
- resultobject | nullThe 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_hashstring | null
- terms_revisioninteger | null
- earned_to_datestring
- retainage_to_datestring
- current_duestringrequired
- prepared_by_idinteger
- contributor_idsinteger[]
- submitted_atstring | null (date-time)
- returned_atstring | null (date-time)
- return_reasonstring | null
- certified_by_idinteger | null
- certified_atstring | null (date-time)
- reviewer_namestring | null
- reviewer_rolestring | null
- reviewer_datestring | null (date)
- certification_notestring | null
- invoice_idinteger | null
- billed_atstring | null (date-time)
- voided_atstring | null (date-time)
- void_reasonstring | null
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Stale revision, wrong state, or the sources behind the application changed422Validation failed
Example request
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}/submitSubmit 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- revisionintegerrequired
Response · 200 · object
- idintegerrequired
- prime_contract_idintegerrequired
- project_idinteger
- entity_idinteger
- numberintegerrequired
- period_endstring (date)required
- finalboolean
- statusstringrequiredOne of: draft, submitted, returned, certified, billed, void.
- revisionintegerrequired
- exclusionsobjectDisallowed job cost entries: entry id -> reason.
- storedobject[]
- resultobject | nullThe 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_hashstring | null
- terms_revisioninteger | null
- earned_to_datestring
- retainage_to_datestring
- current_duestringrequired
- prepared_by_idinteger
- contributor_idsinteger[]
- submitted_atstring | null (date-time)
- returned_atstring | null (date-time)
- return_reasonstring | null
- certified_by_idinteger | null
- certified_atstring | null (date-time)
- reviewer_namestring | null
- reviewer_rolestring | null
- reviewer_datestring | null (date)
- certification_notestring | null
- invoice_idinteger | null
- billed_atstring | null (date-time)
- voided_atstring | null (date-time)
- void_reasonstring | null
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Stale revision, wrong state, or the sources behind the application changed422Validation failed
Example request
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}/voidVoid a GMP application
Needs ar_enter. Voids a draft or returned application with a reason. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- revisionintegerrequired
- reasonstringrequired
Response · 200 · object
- idintegerrequired
- prime_contract_idintegerrequired
- project_idinteger
- entity_idinteger
- numberintegerrequired
- period_endstring (date)required
- finalboolean
- statusstringrequiredOne of: draft, submitted, returned, certified, billed, void.
- revisionintegerrequired
- exclusionsobjectDisallowed job cost entries: entry id -> reason.
- storedobject[]
- resultobject | nullThe 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_hashstring | null
- terms_revisioninteger | null
- earned_to_datestring
- retainage_to_datestring
- current_duestringrequired
- prepared_by_idinteger
- contributor_idsinteger[]
- submitted_atstring | null (date-time)
- returned_atstring | null (date-time)
- return_reasonstring | null
- certified_by_idinteger | null
- certified_atstring | null (date-time)
- reviewer_namestring | null
- reviewer_rolestring | null
- reviewer_datestring | null (date)
- certification_notestring | null
- invoice_idinteger | null
- billed_atstring | null (date-time)
- voided_atstring | null (date-time)
- void_reasonstring | null
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Stale revision, wrong state, or the sources behind the application changed422Validation failed
Example request
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}/withdrawWithdraw 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- revisionintegerrequired
- reasonstringrequired
Response · 200 · object
- idintegerrequired
- prime_contract_idintegerrequired
- project_idinteger
- entity_idinteger
- numberintegerrequired
- period_endstring (date)required
- finalboolean
- statusstringrequiredOne of: draft, submitted, returned, certified, billed, void.
- revisionintegerrequired
- exclusionsobjectDisallowed job cost entries: entry id -> reason.
- storedobject[]
- resultobject | nullThe 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_hashstring | null
- terms_revisioninteger | null
- earned_to_datestring
- retainage_to_datestring
- current_duestringrequired
- prepared_by_idinteger
- contributor_idsinteger[]
- submitted_atstring | null (date-time)
- returned_atstring | null (date-time)
- return_reasonstring | null
- certified_by_idinteger | null
- certified_atstring | null (date-time)
- reviewer_namestring | null
- reviewer_rolestring | null
- reviewer_datestring | null (date)
- certification_notestring | null
- invoice_idinteger | null
- billed_atstring | null (date-time)
- voided_atstring | null (date-time)
- void_reasonstring | null
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Stale revision, wrong state, or the sources behind the application changed422Validation failed
Example request
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}/decisionDecide 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- decisionstringrequiredOne of: approved, rejected.
- notestring
Response · 200 · object
- idinteger
- statusstring
- amountstring
- decided_by_idinteger
- decided_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Already decided or overdraws the contingency
Example request
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/statusGMP 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.
Parameters
- company_idintegerpathrequired
- project_idintegerqueryrequired
Response · 200 · object
- project_idintegerrequired
- contractsobject[]required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/gmp/status" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Receivable
GET/rest/v1.0/companies/{company_id}/accounting/ar/invoicesList 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.
Parameters
- company_idintegerpathrequired
- pageintegerquery
- per_pageintegerquery
- customer_idintegerquery
- statusstringqueryOne of: draft, pending_approval, approved, posted, reversed, cancelled.
- project_idintegerqueryHeader or any line on this project
- date_fromstring (date)queryInvoice date on or after
- date_tostring (date)queryInvoice date on or before
- qstringqueryCase-insensitive match on number, source reference or memo
- overduebooleanquerytrue: posted, unreversed invoices with open receivable due before as_of
- as_ofstring (date)queryOverdue cutoff (default today)
- disputedbooleanquery
- sortstringqueryOne of: date_desc, date_asc, due_asc, due_desc, total_desc, total_asc, number_asc, number_desc.
- updated_sincestring (date-time)queryDelta sync: only rows created or changed at or after this time (ISO 8601 with offset). Switches the list to ascending (updated_at, id) order; page is ignored and Next-Cursor continues it. Re-read with a small overlap (a few seconds) and dedupe by id.
- cursorstringqueryOpaque keyset cursor from a previous response's Next-Cursor header; each page costs the same however deep it is.
Response · 200 · object[]
- entity_idintegerrequired
- customer_idintegerrequired
- source_referencestringrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- memostring | nullrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].descriptionstringrequired
- lines[].amountstringrequired
- lines[].retainage_amountstringrequired
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].releases_invoice_idinteger | nullrequired
- lines[].releases_journal_line_idinteger | nullrequired
- lines[].bucketstring | nullrequiredOne of: current, retainage, null.
- lines[].tax_code_idinteger | nullrequired
- lines[].tax_amountstringrequired
- lines[].payment_application_line_idinteger | nullrequiredThe pay-app (G703) line a bridged pay-app invoice line bills
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- idintegerrequired
- numberstringrequired
- source_typestringrequired
- source_idintegerrequired
- source_revisionintegerrequired
- revisionintegerrequired
- statusstringrequiredOne of: draft, pending_approval, approved, posted, reversed, cancelled.
- currencystringrequired
- totalstringrequired
- retainage_amountstringrequired
- current_amountstringrequired
- open_currentstringrequired
- open_retainagestringrequired
- prepared_by_idintegerrequired
- approved_by_idinteger | nullrequired
- approved_atstring (date-time) | nullrequired
- journal_entry_idinteger | nullrequired
- paid_currentstringrequired
- paid_retainagestringrequired
- corrects_invoice_idinteger | nullrequired
- reversalobject | nullrequired
- reversal.idintegerrequired
- reversal.source_revisionintegerrequired
- reversal.posting_datestring (date)required
- reversal.reasonstringrequired
- reversal.journal_entry_idintegerrequired
- reversal.actor_user_idintegerrequired
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].receipt_idintegerrequired
- applications[].receipt_numberstringrequired
- applications[].journal_line_idintegerrequired
- applications[].bucketstringrequiredOne of: current, retainage.
- applications[].amountstringrequired
- applications[].posting_datestring (date)requiredThe receipt's posting date, or the later cash application's date for rows added after entry.
- applications[].reversalobject | nullrequired
- kindstringrequiredOne of: standard, retainage_release, credit_memo.
- payment_application_idinteger | nullrequiredOwner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
- prime_contract_idinteger | nullrequired
- project_idinteger | nullrequired
- released_retainagestringrequiredRetainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
- tax_amountstringrequired
- disputedbooleanrequired
- dispute_reasonstring | nullrequired
- credited_currentstringrequiredCurrent AR settled by credit memos, including any sales tax they reverse.
- credit_reasonstring | nullrequiredCredit memos only. One of: return, write_off, discount, tax_adjustment, null.
- cancellation_reasonstring | nullrequired
- tax_override_reasonstring | nullrequired
- tax_warningsstring[]requiredSales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
- on_account_amountstring | nullCredit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
- available_creditstring | nullPosted, unreversed credit memos: on-account amount less applications and posted refunds.
- credit_applicationsobject[]On-account credit memos applied to this invoice (while each stands).
- credit_applications[].idinteger
- credit_applications[].credit_memo_idinteger
- credit_applications[].journal_line_idinteger
- credit_applications[].bucketstring
- credit_applications[].amountstring
- credit_applications[].posting_datestring (date)
- outside_contract_reasonstring | nullrequired
Errors
401Authentication required403Tenant, permission or entity access denied404Scoped record not found409State, revision, duplicate source or request conflict422Invalid input, references, configuration or posting period
Example request
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/invoicesCreate 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.
Parameters
- company_idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- request_keystring (uuid)required
- invoiceobjectrequired
- invoice.entity_idintegerrequired
- invoice.customer_idintegerrequired
- invoice.source_referencestringrequired
- invoice.invoice_datestring (date)required
- invoice.posting_datestring (date)required
- invoice.due_datestring (date) | nullOmitted or null: invoice date plus the customer profile's payment terms (net 30 without terms).
- invoice.memostring | null
- invoice.linesobject[]required
- invoice.lines[].account_idinteger | nullRevenue account; null on a retainage release line. On a credit memo line, the account debited (see credit_reason).
- invoice.lines[].project_idinteger | null
- invoice.lines[].cost_code_idinteger | null
- invoice.lines[].descriptionstringrequired
- invoice.lines[].amountstringrequired
- invoice.lines[].retainage_amountstring
- invoice.lines[].releases_invoice_idinteger | nullRetainage release: posted invoice whose retainage moves to current AR.
- invoice.lines[].releases_journal_line_idinteger | nullRetainage release: that invoice's retainage-receivable journal line (see open_items). Its account, project and cost code are used.
- invoice.lines[].tax_code_idinteger | nullActive 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_categorystring | nullContractor 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_idsarray | nullUser-defined dimension values (AcctDimensionValue ids), at most one per dimension; see oas-dimensions.json.
- invoice.kindstringretainage_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_reasonstring | nullCredit 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_reasonstring | nullCharges 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_reasonstring | nullA 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).
- correctionobject
- correction.invoice_idintegerrequired
- correction.revisionintegerrequired
Response · 200 · object
- entity_idintegerrequired
- customer_idintegerrequired
- source_referencestringrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- memostring | nullrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].descriptionstringrequired
- lines[].amountstringrequired
- lines[].retainage_amountstringrequired
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].releases_invoice_idinteger | nullrequired
- lines[].releases_journal_line_idinteger | nullrequired
- lines[].bucketstring | nullrequiredOne of: current, retainage, null.
- lines[].tax_code_idinteger | nullrequired
- lines[].tax_amountstringrequired
- lines[].payment_application_line_idinteger | nullrequiredThe pay-app (G703) line a bridged pay-app invoice line bills
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- idintegerrequired
- numberstringrequired
- source_typestringrequired
- source_idintegerrequired
- source_revisionintegerrequired
- revisionintegerrequired
- statusstringrequiredOne of: draft, pending_approval, approved, posted, reversed, cancelled.
- currencystringrequired
- totalstringrequired
- retainage_amountstringrequired
- current_amountstringrequired
- open_currentstringrequired
- open_retainagestringrequired
- prepared_by_idintegerrequired
- approved_by_idinteger | nullrequired
- approved_atstring (date-time) | nullrequired
- journal_entry_idinteger | nullrequired
- paid_currentstringrequired
- paid_retainagestringrequired
- corrects_invoice_idinteger | nullrequired
- reversalobject | nullrequired
- reversal.idintegerrequired
- reversal.source_revisionintegerrequired
- reversal.posting_datestring (date)required
- reversal.reasonstringrequired
- reversal.journal_entry_idintegerrequired
- reversal.actor_user_idintegerrequired
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].receipt_idintegerrequired
- applications[].receipt_numberstringrequired
- applications[].journal_line_idintegerrequired
- applications[].bucketstringrequiredOne of: current, retainage.
- applications[].amountstringrequired
- applications[].posting_datestring (date)requiredThe receipt's posting date, or the later cash application's date for rows added after entry.
- applications[].reversalobject | nullrequired
- kindstringrequiredOne of: standard, retainage_release, credit_memo.
- payment_application_idinteger | nullrequiredOwner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
- prime_contract_idinteger | nullrequired
- project_idinteger | nullrequired
- released_retainagestringrequiredRetainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
- tax_amountstringrequired
- disputedbooleanrequired
- dispute_reasonstring | nullrequired
- credited_currentstringrequiredCurrent AR settled by credit memos, including any sales tax they reverse.
- credit_reasonstring | nullrequiredCredit memos only. One of: return, write_off, discount, tax_adjustment, null.
- cancellation_reasonstring | nullrequired
- tax_override_reasonstring | nullrequired
- tax_warningsstring[]requiredSales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
- on_account_amountstring | nullCredit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
- available_creditstring | nullPosted, unreversed credit memos: on-account amount less applications and posted refunds.
- credit_applicationsobject[]On-account credit memos applied to this invoice (while each stands).
- credit_applications[].idinteger
- credit_applications[].credit_memo_idinteger
- credit_applications[].journal_line_idinteger
- credit_applications[].bucketstring
- credit_applications[].amountstring
- credit_applications[].posting_datestring (date)
- outside_contract_reasonstring | nullrequired
Errors
400Malformed JSON request body401Authentication required403Tenant, permission or entity access denied404Scoped record not found409State, revision, duplicate source or request conflict422Invalid input, references, configuration or posting period
Example request
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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- entity_idintegerrequired
- customer_idintegerrequired
- source_referencestringrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- memostring | nullrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].descriptionstringrequired
- lines[].amountstringrequired
- lines[].retainage_amountstringrequired
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].releases_invoice_idinteger | nullrequired
- lines[].releases_journal_line_idinteger | nullrequired
- lines[].bucketstring | nullrequiredOne of: current, retainage, null.
- lines[].tax_code_idinteger | nullrequired
- lines[].tax_amountstringrequired
- lines[].payment_application_line_idinteger | nullrequiredThe pay-app (G703) line a bridged pay-app invoice line bills
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- idintegerrequired
- numberstringrequired
- source_typestringrequired
- source_idintegerrequired
- source_revisionintegerrequired
- revisionintegerrequired
- statusstringrequiredOne of: draft, pending_approval, approved, posted, reversed, cancelled.
- currencystringrequired
- totalstringrequired
- retainage_amountstringrequired
- current_amountstringrequired
- open_currentstringrequired
- open_retainagestringrequired
- prepared_by_idintegerrequired
- approved_by_idinteger | nullrequired
- approved_atstring (date-time) | nullrequired
- journal_entry_idinteger | nullrequired
- paid_currentstringrequired
- paid_retainagestringrequired
- corrects_invoice_idinteger | nullrequired
- reversalobject | nullrequired
- reversal.idintegerrequired
- reversal.source_revisionintegerrequired
- reversal.posting_datestring (date)required
- reversal.reasonstringrequired
- reversal.journal_entry_idintegerrequired
- reversal.actor_user_idintegerrequired
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].receipt_idintegerrequired
- applications[].receipt_numberstringrequired
- applications[].journal_line_idintegerrequired
- applications[].bucketstringrequiredOne of: current, retainage.
- applications[].amountstringrequired
- applications[].posting_datestring (date)requiredThe receipt's posting date, or the later cash application's date for rows added after entry.
- applications[].reversalobject | nullrequired
- kindstringrequiredOne of: standard, retainage_release, credit_memo.
- payment_application_idinteger | nullrequiredOwner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
- prime_contract_idinteger | nullrequired
- project_idinteger | nullrequired
- released_retainagestringrequiredRetainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
- tax_amountstringrequired
- disputedbooleanrequired
- dispute_reasonstring | nullrequired
- credited_currentstringrequiredCurrent AR settled by credit memos, including any sales tax they reverse.
- credit_reasonstring | nullrequiredCredit memos only. One of: return, write_off, discount, tax_adjustment, null.
- cancellation_reasonstring | nullrequired
- tax_override_reasonstring | nullrequired
- tax_warningsstring[]requiredSales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
- on_account_amountstring | nullCredit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
- available_creditstring | nullPosted, unreversed credit memos: on-account amount less applications and posted refunds.
- credit_applicationsobject[]On-account credit memos applied to this invoice (while each stands).
- credit_applications[].idinteger
- credit_applications[].credit_memo_idinteger
- credit_applications[].journal_line_idinteger
- credit_applications[].bucketstring
- credit_applications[].amountstring
- credit_applications[].posting_datestring (date)
- outside_contract_reasonstring | nullrequired
Errors
401Authentication required403Tenant, permission or entity access denied404Scoped record not found409State, revision, duplicate source or request conflict422Invalid input, references, configuration or posting period
Example request
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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- revisionintegerrequired
- invoiceobjectrequired
- invoice.entity_idintegerrequired
- invoice.customer_idintegerrequired
- invoice.source_referencestringrequired
- invoice.invoice_datestring (date)required
- invoice.posting_datestring (date)required
- invoice.due_datestring (date) | nullOmitted or null: invoice date plus the customer profile's payment terms (net 30 without terms).
- invoice.memostring | null
- invoice.linesobject[]required
- invoice.lines[].account_idinteger | nullRevenue account; null on a retainage release line. On a credit memo line, the account debited (see credit_reason).
- invoice.lines[].project_idinteger | null
- invoice.lines[].cost_code_idinteger | null
- invoice.lines[].descriptionstringrequired
- invoice.lines[].amountstringrequired
- invoice.lines[].retainage_amountstring
- invoice.lines[].releases_invoice_idinteger | nullRetainage release: posted invoice whose retainage moves to current AR.
- invoice.lines[].releases_journal_line_idinteger | nullRetainage release: that invoice's retainage-receivable journal line (see open_items). Its account, project and cost code are used.
- invoice.lines[].tax_code_idinteger | nullActive 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_categorystring | nullContractor 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_idsarray | nullUser-defined dimension values (AcctDimensionValue ids), at most one per dimension; see oas-dimensions.json.
- invoice.kindstringretainage_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_reasonstring | nullCredit 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_reasonstring | nullCharges 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_reasonstring | nullA 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_idintegerrequired
- customer_idintegerrequired
- source_referencestringrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- memostring | nullrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].descriptionstringrequired
- lines[].amountstringrequired
- lines[].retainage_amountstringrequired
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].releases_invoice_idinteger | nullrequired
- lines[].releases_journal_line_idinteger | nullrequired
- lines[].bucketstring | nullrequiredOne of: current, retainage, null.
- lines[].tax_code_idinteger | nullrequired
- lines[].tax_amountstringrequired
- lines[].payment_application_line_idinteger | nullrequiredThe pay-app (G703) line a bridged pay-app invoice line bills
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- idintegerrequired
- numberstringrequired
- source_typestringrequired
- source_idintegerrequired
- source_revisionintegerrequired
- revisionintegerrequired
- statusstringrequiredOne of: draft, pending_approval, approved, posted, reversed, cancelled.
- currencystringrequired
- totalstringrequired
- retainage_amountstringrequired
- current_amountstringrequired
- open_currentstringrequired
- open_retainagestringrequired
- prepared_by_idintegerrequired
- approved_by_idinteger | nullrequired
- approved_atstring (date-time) | nullrequired
- journal_entry_idinteger | nullrequired
- paid_currentstringrequired
- paid_retainagestringrequired
- corrects_invoice_idinteger | nullrequired
- reversalobject | nullrequired
- reversal.idintegerrequired
- reversal.source_revisionintegerrequired
- reversal.posting_datestring (date)required
- reversal.reasonstringrequired
- reversal.journal_entry_idintegerrequired
- reversal.actor_user_idintegerrequired
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].receipt_idintegerrequired
- applications[].receipt_numberstringrequired
- applications[].journal_line_idintegerrequired
- applications[].bucketstringrequiredOne of: current, retainage.
- applications[].amountstringrequired
- applications[].posting_datestring (date)requiredThe receipt's posting date, or the later cash application's date for rows added after entry.
- applications[].reversalobject | nullrequired
- kindstringrequiredOne of: standard, retainage_release, credit_memo.
- payment_application_idinteger | nullrequiredOwner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
- prime_contract_idinteger | nullrequired
- project_idinteger | nullrequired
- released_retainagestringrequiredRetainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
- tax_amountstringrequired
- disputedbooleanrequired
- dispute_reasonstring | nullrequired
- credited_currentstringrequiredCurrent AR settled by credit memos, including any sales tax they reverse.
- credit_reasonstring | nullrequiredCredit memos only. One of: return, write_off, discount, tax_adjustment, null.
- cancellation_reasonstring | nullrequired
- tax_override_reasonstring | nullrequired
- tax_warningsstring[]requiredSales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
- on_account_amountstring | nullCredit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
- available_creditstring | nullPosted, unreversed credit memos: on-account amount less applications and posted refunds.
- credit_applicationsobject[]On-account credit memos applied to this invoice (while each stands).
- credit_applications[].idinteger
- credit_applications[].credit_memo_idinteger
- credit_applications[].journal_line_idinteger
- credit_applications[].bucketstring
- credit_applications[].amountstring
- credit_applications[].posting_datestring (date)
- outside_contract_reasonstring | nullrequired
Errors
400Malformed JSON request body401Authentication required403Tenant, permission or entity access denied404Scoped record not found409State, revision, duplicate source or request conflict422Invalid input, references, configuration or posting period
Example request
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}/attachmentsList attachments on a AR invoice
Oldest first. Needs view_ledger and the parent's entity scope. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object[]
- idintegerrequired
- doc_typestringrequiredOne of: journal_entry, ap_bill, vendor, ap_compliance, ap_lien_waiver, ar_invoice, ar_receipt, bank_transaction, fixed_asset, wip_snapshot, account_rec, policy_signoff.
- doc_idintegerrequired
- namestringrequired
- content_typestringrequired
- size_bytesintegerrequired
- sha256stringrequired
- uploaded_byobjectrequired
- uploaded_by.idintegerrequired
- uploaded_by.namestring | nullrequired
- created_atstring (date-time)required
- download_urlstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/invoices/1/attachments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Receivable
POST/rest/v1.0/companies/{company_id}/accounting/ar/invoices/{id}/attachmentsAttach 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- filestring (binary)required
Response · 201 · object
- idintegerrequired
- doc_typestringrequiredOne of: journal_entry, ap_bill, vendor, ap_compliance, ap_lien_waiver, ar_invoice, ar_receipt, bank_transaction, fixed_asset, wip_snapshot, account_rec, policy_signoff.
- doc_idintegerrequired
- namestringrequired
- content_typestringrequired
- size_bytesintegerrequired
- sha256stringrequired
- uploaded_byobjectrequired
- uploaded_by.idintegerrequired
- uploaded_by.namestring | nullrequired
- created_atstring (date-time)required
- download_urlstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace404Not found in this company409Idempotency-Key reused for a different request or still in progress413Request body too large422Missing file, empty file, too large, or a type that is not allowed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/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_applicationsApply 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- request_keystring (uuid)required
- posting_datestring (date)required
- applicationsobject[]required
- applications[].invoice_idintegerrequired
- applications[].invoice_revisionintegerrequired
- applications[].journal_line_idintegerrequired
- applications[].bucketstringrequiredOne of: current, retainage.
- applications[].amountstringrequired
Response · 201 · object[]
- idintegerrequired
- credit_memo_idintegerrequired
- invoice_idintegerrequired
- invoice_revisioninteger
- journal_line_idintegerrequired
- bucketstringrequiredOne of: current, retainage.
- amountstringrequired
- posting_datestring (date)required
- journal_entry_idintegerrequired
- actor_user_idinteger
Errors
400Malformed JSON request body401Authentication required403Scope or separation of duties denied404Scoped source not found409State, revision, overapplication or idempotency conflict422Invalid data, dates, account or closed period
Example request
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}/disputeFlag 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- disputedbooleanrequired
- reasonstring | nullRequired when disputed.
Response · 200 · object
- entity_idintegerrequired
- customer_idintegerrequired
- source_referencestringrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- memostring | nullrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].descriptionstringrequired
- lines[].amountstringrequired
- lines[].retainage_amountstringrequired
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].releases_invoice_idinteger | nullrequired
- lines[].releases_journal_line_idinteger | nullrequired
- lines[].bucketstring | nullrequiredOne of: current, retainage, null.
- lines[].tax_code_idinteger | nullrequired
- lines[].tax_amountstringrequired
- lines[].payment_application_line_idinteger | nullrequiredThe pay-app (G703) line a bridged pay-app invoice line bills
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- idintegerrequired
- numberstringrequired
- source_typestringrequired
- source_idintegerrequired
- source_revisionintegerrequired
- revisionintegerrequired
- statusstringrequiredOne of: draft, pending_approval, approved, posted, reversed, cancelled.
- currencystringrequired
- totalstringrequired
- retainage_amountstringrequired
- current_amountstringrequired
- open_currentstringrequired
- open_retainagestringrequired
- prepared_by_idintegerrequired
- approved_by_idinteger | nullrequired
- approved_atstring (date-time) | nullrequired
- journal_entry_idinteger | nullrequired
- paid_currentstringrequired
- paid_retainagestringrequired
- corrects_invoice_idinteger | nullrequired
- reversalobject | nullrequired
- reversal.idintegerrequired
- reversal.source_revisionintegerrequired
- reversal.posting_datestring (date)required
- reversal.reasonstringrequired
- reversal.journal_entry_idintegerrequired
- reversal.actor_user_idintegerrequired
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].receipt_idintegerrequired
- applications[].receipt_numberstringrequired
- applications[].journal_line_idintegerrequired
- applications[].bucketstringrequiredOne of: current, retainage.
- applications[].amountstringrequired
- applications[].posting_datestring (date)requiredThe receipt's posting date, or the later cash application's date for rows added after entry.
- applications[].reversalobject | nullrequired
- kindstringrequiredOne of: standard, retainage_release, credit_memo.
- payment_application_idinteger | nullrequiredOwner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
- prime_contract_idinteger | nullrequired
- project_idinteger | nullrequired
- released_retainagestringrequiredRetainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
- tax_amountstringrequired
- disputedbooleanrequired
- dispute_reasonstring | nullrequired
- credited_currentstringrequiredCurrent AR settled by credit memos, including any sales tax they reverse.
- credit_reasonstring | nullrequiredCredit memos only. One of: return, write_off, discount, tax_adjustment, null.
- cancellation_reasonstring | nullrequired
- tax_override_reasonstring | nullrequired
- tax_warningsstring[]requiredSales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
- on_account_amountstring | nullCredit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
- available_creditstring | nullPosted, unreversed credit memos: on-account amount less applications and posted refunds.
- credit_applicationsobject[]On-account credit memos applied to this invoice (while each stands).
- credit_applications[].idinteger
- credit_applications[].credit_memo_idinteger
- credit_applications[].journal_line_idinteger
- credit_applications[].bucketstring
- credit_applications[].amountstring
- credit_applications[].posting_datestring (date)
- outside_contract_reasonstring | nullrequired
Errors
400Malformed JSON request body401Authentication required403Scope or separation of duties denied404Scoped source not found409State, revision, overapplication or idempotency conflict422Invalid data, dates, account or closed period
Example request
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}/pdfInvoice PDF
Any accounting viewer in the invoice's entity. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · string (binary)
No documented fields.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company
Example request
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}/reverseAppend 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- request_keystring (uuid)required
- revisionintegerrequired
- datestring (date)required
- reasonstringrequired
- nsfbooleanReceipt 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
- idintegerrequired
- source_revisionintegerrequired
- posting_datestring (date)required
- reasonstringrequired
- journal_entry_idintegerrequired
- actor_user_idintegerrequired
Errors
400Malformed JSON request body401Authentication required403Scope or separation of duties denied404Scoped source not found409State, revision, overapplication or idempotency conflict422Invalid data, dates, account or closed period
Example request
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}/sendQueue 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 202 · object
- invoice_idintegerrequired
- tostringrequired
- job_idintegerrequired
- statusstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Conflict422Validation failed or the ledger refused the change
Example request
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}/transitionSubmit, 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- revisionintegerrequired
- actionstringrequiredOne of: submit, return, approve, post, cancel.
- reasonstring
Response · 200 · object
- entity_idintegerrequired
- customer_idintegerrequired
- source_referencestringrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- memostring | nullrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].descriptionstringrequired
- lines[].amountstringrequired
- lines[].retainage_amountstringrequired
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].releases_invoice_idinteger | nullrequired
- lines[].releases_journal_line_idinteger | nullrequired
- lines[].bucketstring | nullrequiredOne of: current, retainage, null.
- lines[].tax_code_idinteger | nullrequired
- lines[].tax_amountstringrequired
- lines[].payment_application_line_idinteger | nullrequiredThe pay-app (G703) line a bridged pay-app invoice line bills
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- idintegerrequired
- numberstringrequired
- source_typestringrequired
- source_idintegerrequired
- source_revisionintegerrequired
- revisionintegerrequired
- statusstringrequiredOne of: draft, pending_approval, approved, posted, reversed, cancelled.
- currencystringrequired
- totalstringrequired
- retainage_amountstringrequired
- current_amountstringrequired
- open_currentstringrequired
- open_retainagestringrequired
- prepared_by_idintegerrequired
- approved_by_idinteger | nullrequired
- approved_atstring (date-time) | nullrequired
- journal_entry_idinteger | nullrequired
- paid_currentstringrequired
- paid_retainagestringrequired
- corrects_invoice_idinteger | nullrequired
- reversalobject | nullrequired
- reversal.idintegerrequired
- reversal.source_revisionintegerrequired
- reversal.posting_datestring (date)required
- reversal.reasonstringrequired
- reversal.journal_entry_idintegerrequired
- reversal.actor_user_idintegerrequired
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].receipt_idintegerrequired
- applications[].receipt_numberstringrequired
- applications[].journal_line_idintegerrequired
- applications[].bucketstringrequiredOne of: current, retainage.
- applications[].amountstringrequired
- applications[].posting_datestring (date)requiredThe receipt's posting date, or the later cash application's date for rows added after entry.
- applications[].reversalobject | nullrequired
- kindstringrequiredOne of: standard, retainage_release, credit_memo.
- payment_application_idinteger | nullrequiredOwner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
- prime_contract_idinteger | nullrequired
- project_idinteger | nullrequired
- released_retainagestringrequiredRetainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
- tax_amountstringrequired
- disputedbooleanrequired
- dispute_reasonstring | nullrequired
- credited_currentstringrequiredCurrent AR settled by credit memos, including any sales tax they reverse.
- credit_reasonstring | nullrequiredCredit memos only. One of: return, write_off, discount, tax_adjustment, null.
- cancellation_reasonstring | nullrequired
- tax_override_reasonstring | nullrequired
- tax_warningsstring[]requiredSales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
- on_account_amountstring | nullCredit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
- available_creditstring | nullPosted, unreversed credit memos: on-account amount less applications and posted refunds.
- credit_applicationsobject[]On-account credit memos applied to this invoice (while each stands).
- credit_applications[].idinteger
- credit_applications[].credit_memo_idinteger
- credit_applications[].journal_line_idinteger
- credit_applications[].bucketstring
- credit_applications[].amountstring
- credit_applications[].posting_datestring (date)
- outside_contract_reasonstring | nullrequired
Errors
400Malformed JSON request body401Authentication required403Tenant, permission or entity access denied404Scoped record not found409State, revision, duplicate source or request conflict422Invalid input, references, configuration or posting period
Example request
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_billingDraft 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.
Parameters
- company_idintegerpathrequired
Request body
- request_keystring (uuid)required
- prime_contract_idintegerrequired
- entity_idinteger
- revenue_account_idinteger
- invoice_datestring (date)required
- posting_datestring (date)
- due_datestring (date)
- source_referencestring
- memostring
- billingobjectrequired
- billing.methodanyrequired
- billing.inputobjectrequired
- billing.input.linesobject[]required
- billing.input.lines[].idstringrequired
- billing.input.lines[].ticket_idstring
- billing.input.lines[].cost_typestringrequiredOne of: labor, material, equipment, subcontract, other.
- billing.input.lines[].descriptionstringrequired
- billing.input.lines[].quantitystring
- billing.input.lines[].rate_codestringPrices 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[].coststring
- billing.input.lines[].taxableboolean
- billing.input.tax_code_idinteger
Response · 200 · object
- entity_idintegerrequired
- customer_idintegerrequired
- source_referencestringrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- memostring | nullrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].descriptionstringrequired
- lines[].amountstringrequired
- lines[].retainage_amountstringrequired
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].releases_invoice_idinteger | nullrequired
- lines[].releases_journal_line_idinteger | nullrequired
- lines[].bucketstring | nullrequiredOne of: current, retainage, null.
- lines[].tax_code_idinteger | nullrequired
- lines[].tax_amountstringrequired
- lines[].payment_application_line_idinteger | nullrequiredThe pay-app (G703) line a bridged pay-app invoice line bills
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- idintegerrequired
- numberstringrequired
- source_typestringrequired
- source_idintegerrequired
- source_revisionintegerrequired
- revisionintegerrequired
- statusstringrequiredOne of: draft, pending_approval, approved, posted, reversed, cancelled.
- currencystringrequired
- totalstringrequired
- retainage_amountstringrequired
- current_amountstringrequired
- open_currentstringrequired
- open_retainagestringrequired
- prepared_by_idintegerrequired
- approved_by_idinteger | nullrequired
- approved_atstring (date-time) | nullrequired
- journal_entry_idinteger | nullrequired
- paid_currentstringrequired
- paid_retainagestringrequired
- corrects_invoice_idinteger | nullrequired
- reversalobject | nullrequired
- reversal.idintegerrequired
- reversal.source_revisionintegerrequired
- reversal.posting_datestring (date)required
- reversal.reasonstringrequired
- reversal.journal_entry_idintegerrequired
- reversal.actor_user_idintegerrequired
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].receipt_idintegerrequired
- applications[].receipt_numberstringrequired
- applications[].journal_line_idintegerrequired
- applications[].bucketstringrequiredOne of: current, retainage.
- applications[].amountstringrequired
- applications[].posting_datestring (date)requiredThe receipt's posting date, or the later cash application's date for rows added after entry.
- applications[].reversalobject | nullrequired
- kindstringrequiredOne of: standard, retainage_release, credit_memo.
- payment_application_idinteger | nullrequiredOwner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
- prime_contract_idinteger | nullrequired
- project_idinteger | nullrequired
- released_retainagestringrequiredRetainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
- tax_amountstringrequired
- disputedbooleanrequired
- dispute_reasonstring | nullrequired
- credited_currentstringrequiredCurrent AR settled by credit memos, including any sales tax they reverse.
- credit_reasonstring | nullrequiredCredit memos only. One of: return, write_off, discount, tax_adjustment, null.
- cancellation_reasonstring | nullrequired
- tax_override_reasonstring | nullrequired
- tax_warningsstring[]requiredSales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
- on_account_amountstring | nullCredit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
- available_creditstring | nullPosted, unreversed credit memos: on-account amount less applications and posted refunds.
- credit_applicationsobject[]On-account credit memos applied to this invoice (while each stands).
- credit_applications[].idinteger
- credit_applications[].credit_memo_idinteger
- credit_applications[].journal_line_idinteger
- credit_applications[].bucketstring
- credit_applications[].amountstring
- credit_applications[].posting_datestring (date)
- outside_contract_reasonstring | nullrequired
- calcobject
- calc.retainagestring
- calc.explainany
Errors
400Malformed JSON request body401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Conflict422Validation failed or the ledger refused the change
Example request
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_applicationBill 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.
Parameters
- company_idintegerpathrequired
Request body
- payment_application_idintegerrequired
- entity_idintegerDefaults 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_idintegerDefaults to the CONTRACT_REVENUE account.
- invoice_datestring (date)Defaults to the pay app billing date, else period end.
- posting_datestring (date)Defaults to invoice_date (a re-bill after reversal: no earlier than the reversal date).
- due_datestring (date)Defaults to invoice_date plus the owner's profile terms (net 30 without terms).
- dimension_value_idsinteger[]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_idintegerrequired
- customer_idintegerrequired
- source_referencestringrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- memostring | nullrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].descriptionstringrequired
- lines[].amountstringrequired
- lines[].retainage_amountstringrequired
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].releases_invoice_idinteger | nullrequired
- lines[].releases_journal_line_idinteger | nullrequired
- lines[].bucketstring | nullrequiredOne of: current, retainage, null.
- lines[].tax_code_idinteger | nullrequired
- lines[].tax_amountstringrequired
- lines[].payment_application_line_idinteger | nullrequiredThe pay-app (G703) line a bridged pay-app invoice line bills
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- idintegerrequired
- numberstringrequired
- source_typestringrequired
- source_idintegerrequired
- source_revisionintegerrequired
- revisionintegerrequired
- statusstringrequiredOne of: draft, pending_approval, approved, posted, reversed, cancelled.
- currencystringrequired
- totalstringrequired
- retainage_amountstringrequired
- current_amountstringrequired
- open_currentstringrequired
- open_retainagestringrequired
- prepared_by_idintegerrequired
- approved_by_idinteger | nullrequired
- approved_atstring (date-time) | nullrequired
- journal_entry_idinteger | nullrequired
- paid_currentstringrequired
- paid_retainagestringrequired
- corrects_invoice_idinteger | nullrequired
- reversalobject | nullrequired
- reversal.idintegerrequired
- reversal.source_revisionintegerrequired
- reversal.posting_datestring (date)required
- reversal.reasonstringrequired
- reversal.journal_entry_idintegerrequired
- reversal.actor_user_idintegerrequired
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].receipt_idintegerrequired
- applications[].receipt_numberstringrequired
- applications[].journal_line_idintegerrequired
- applications[].bucketstringrequiredOne of: current, retainage.
- applications[].amountstringrequired
- applications[].posting_datestring (date)requiredThe receipt's posting date, or the later cash application's date for rows added after entry.
- applications[].reversalobject | nullrequired
- kindstringrequiredOne of: standard, retainage_release, credit_memo.
- payment_application_idinteger | nullrequiredOwner pay app this invoice bills (a credit memo for a negative pay app). Cleared when the invoice is cancelled.
- prime_contract_idinteger | nullrequired
- project_idinteger | nullrequired
- released_retainagestringrequiredRetainage moved to current AR by posted, unreversed release lines; open_retainage is net of it.
- tax_amountstringrequired
- disputedbooleanrequired
- dispute_reasonstring | nullrequired
- credited_currentstringrequiredCurrent AR settled by credit memos, including any sales tax they reverse.
- credit_reasonstring | nullrequiredCredit memos only. One of: return, write_off, discount, tax_adjustment, null.
- cancellation_reasonstring | nullrequired
- tax_override_reasonstring | nullrequired
- tax_warningsstring[]requiredSales tax findings at entry: overridden blocks (prefixed Override:), expired exemption certificates, untaxed billing on retailer or gross-receipts jobs.
- on_account_amountstring | nullCredit memos: lines that settle no invoice (amount plus tax), held as customer credit on account.
- available_creditstring | nullPosted, unreversed credit memos: on-account amount less applications and posted refunds.
- credit_applicationsobject[]On-account credit memos applied to this invoice (while each stands).
- credit_applications[].idinteger
- credit_applications[].credit_memo_idinteger
- credit_applications[].journal_line_idinteger
- credit_applications[].bucketstring
- credit_applications[].amountstring
- credit_applications[].posting_datestring (date)
- outside_contract_reasonstring | nullrequired
Errors
400Malformed JSON request body401Authentication required403Tenant, permission or entity access denied404Scoped record not found409State, revision, duplicate source or request conflict422Invalid input, references, configuration or posting period
Example request
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}/pdfG702/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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · string (binary)
No documented fields.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Conflict422Validation failed or the ledger refused the change
Example request
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_methodSet 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- billing_methodstringrequiredOne of: progress, tm, cost_plus, unit_price, gmp, milestone.
- conversion_reasonstring | nullWhy a contract already billed changes method.
Response · 200 · object
- idintegerrequired
- billing_methodstringrequiredOne of: progress, tm, cost_plus, unit_price, gmp, milestone.
Errors
400Malformed JSON request body401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409The contract is already billed and no conversion reason was given422Validation failed or the ledger refused the change
Example request
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_termsGet 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- prime_contract_idintegerrequired
- billing_methodstringrequiredOne of: progress, tm, cost_plus, unit_price, gmp, milestone.
- contract_retainage_pctstring | nullrequired
- revisionintegerrequired0 before any terms are proposed; approve names the revision it approves.
- termsobject | nullrequiredThe approved terms billing uses (null: none; billing is then 422).
- approved_by_idinteger | nullrequired
- approved_atstring (date-time) | nullrequired
- proposedobject | nullrequiredA change waiting for approval (unit_items carry the snapshotted bid).
- proposed_by_idinteger | nullrequired
- proposed_atstring (date-time) | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, project-scoped grant, or wrong company404Not found in this company
Example request
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_termsPropose 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- ntestring | nullT&M not-to-exceed; null is uncapped.
- markupsobjectT&M markup percent by cost type (labor, material, equipment, subcontract, other).
- labor_ratesobject[]T&M rates a ticket line prices its quantity at (rate_code); codes are unique.
- labor_rates[].codestringrequired
- labor_rates[].ratestringrequired
- gmpstring | nullCost-plus guaranteed maximum price (cumulative cost plus fee billed is capped at it), and the GMP settlement's.
- feeobject | 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_pctstring | nullGMP settlement: the contractor's share of savings below the GMP.
- retainage_pctstring | nullNull: the prime contract's retainage_percent.
- unit_itemsobject[]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_idintegerrequired
- unit_items[].tolerance_pctstring
- contract_amountstring | nullMilestone billing: the amount the percent milestones split.
- milestonesobject[]Milestone schedule; ids are unique.
- milestones[].idstringrequired
- milestones[].namestringrequired
- milestones[].pctstring
- milestones[].amountstring
- gmp_setupobject | nullGMP 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_pctstring | null
- gmp_setup.general_conditionsobject | null
- gmp_setup.contingencyobject | null
- gmp_setup.allowancesobject[]
- gmp_setup.markupsobject[]
- gmp_setup.category_nteobject[]
- gmp_setup.non_reimbursable_cost_code_idsinteger[]
- gmp_setup.burden_reimbursableboolean
- gmp_setup.retainage_step_downobject | null
- gmp_setup.stored_retainage_pctstring | null
Response · 200 · object
- prime_contract_idintegerrequired
- billing_methodstringrequiredOne of: progress, tm, cost_plus, unit_price, gmp, milestone.
- contract_retainage_pctstring | nullrequired
- revisionintegerrequired0 before any terms are proposed; approve names the revision it approves.
- termsobject | nullrequiredThe approved terms billing uses (null: none; billing is then 422).
- approved_by_idinteger | nullrequired
- approved_atstring (date-time) | nullrequired
- proposedobject | nullrequiredA change waiting for approval (unit_items carry the snapshotted bid).
- proposed_by_idinteger | nullrequired
- proposed_atstring (date-time) | nullrequired
Errors
400Malformed JSON request body401Missing or invalid bearer token403No accounting access, missing permission, project-scoped grant, wrong company, or read-only workspace404Not found in this company422Validation failed
Example request
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/approveApprove 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- revisionintegerrequired
Response · 200 · object
- prime_contract_idintegerrequired
- billing_methodstringrequiredOne of: progress, tm, cost_plus, unit_price, gmp, milestone.
- contract_retainage_pctstring | nullrequired
- revisionintegerrequired0 before any terms are proposed; approve names the revision it approves.
- termsobject | nullrequiredThe approved terms billing uses (null: none; billing is then 422).
- approved_by_idinteger | nullrequired
- approved_atstring (date-time) | nullrequired
- proposedobject | nullrequiredA change waiting for approval (unit_items carry the snapshotted bid).
- proposed_by_idinteger | nullrequired
- proposed_atstring (date-time) | nullrequired
Errors
400Malformed JSON request body401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, project-scoped grant, wrong company, or read-only workspace404Not found in this company409Nothing proposed, or the proposed revision changed422Validation failed
Example request
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}/closeoutGet 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- prime_contract_idintegerrequired
- requiredstring[]required
- receivedstring[]required
- missingstring[]required
- restricted_submittal_evidencebooleanWhen true, the response contains only manual checks because submittal evidence is restricted.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/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}/closeoutSet 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- requiredstring[]required
- receivedstring[]
Response · 200 · object
- prime_contract_idintegerrequired
- requiredstring[]required
- receivedstring[]required
- missingstring[]required
Errors
400Malformed JSON request body401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed or the ledger refused the change
Example request
curl -X 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_applicationsList 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- contractobjectrequired
- terms_revisioninteger | null
- applicationsobject[]required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Not a cost_plus GMP contract
Example request
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_applicationsStart 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- period_endstring (date)required
- finalboolean
Response · 201 · object
- idintegerrequired
- prime_contract_idintegerrequired
- project_idinteger
- entity_idinteger
- numberintegerrequired
- period_endstring (date)required
- finalboolean
- statusstringrequiredOne of: draft, submitted, returned, certified, billed, void.
- revisionintegerrequired
- exclusionsobjectDisallowed job cost entries: entry id -> reason.
- storedobject[]
- resultobject | nullThe 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_hashstring | null
- terms_revisioninteger | null
- earned_to_datestring
- retainage_to_datestring
- current_duestringrequired
- prepared_by_idinteger
- contributor_idsinteger[]
- submitted_atstring | null (date-time)
- returned_atstring | null (date-time)
- return_reasonstring | null
- certified_by_idinteger | null
- certified_atstring | null (date-time)
- reviewer_namestring | null
- reviewer_rolestring | null
- reviewer_datestring | null (date)
- certification_notestring | null
- invoice_idinteger | null
- billed_atstring | null (date-time)
- voided_atstring | null (date-time)
- void_reasonstring | null
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Stale revision, wrong state, or the sources behind the application changed422Validation failed
Example request
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_closeoutGMP 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- prime_contract_idintegerrequired
- last_applicationobject | null
- reconciliationobjectrequired
- billed_to_datestring
- billed_postedstring
- closeoutobject
- readyobjectrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/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_drawsList GMP contingency and allowance draws
The usage log of the GMP contract's contingency transfers and allowance adjustments. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- drawsobject[]
- draws[].idinteger
- draws[].prime_contract_idinteger
- draws[].sourcestringOne of: contractor_contingency, owner_contingency, allowance.
- draws[].allowance_keystring | null
- draws[].cost_code_idinteger | null
- draws[].amountstring
- draws[].reasonstring
- draws[].referencestring | null
- draws[].statusstringOne of: proposed, approved, rejected.
- draws[].proposed_by_idinteger
- draws[].decided_by_idinteger | null
- draws[].decided_atstring | null (date-time)
- draws[].decision_notestring | null
- draws[].created_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/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_drawsPropose 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- sourcestringrequiredOne of: contractor_contingency, owner_contingency, allowance.
- allowance_keystring | null
- cost_code_idinteger | null
- amountstringrequired
- reasonstringrequired
- referencestring
Response · 201 · object
- idinteger
- prime_contract_idinteger
- sourcestringOne of: contractor_contingency, owner_contingency, allowance.
- allowance_keystring | null
- cost_code_idinteger | null
- amountstring
- reasonstring
- referencestring | null
- statusstringOne of: proposed, approved, rejected.
- proposed_by_idinteger
- decided_by_idinteger | null
- decided_atstring | null (date-time)
- decision_notestring | null
- created_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/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/receiptsReceipt 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.
Parameters
- company_idintegerpathrequired
- pageintegerquery
- customer_idintegerquery
- per_pageintegerquery
Response · 200 · object[]
- idintegerrequired
- numberstringrequired
- entity_idintegerrequired
- customer_idintegerrequired
- referencestringrequired
- posting_datestring (date)required
- currencystringrequired
- amountstringrequired
- cash_account_idintegerrequired
- revisionintegerrequired
- source_typestringrequired
- source_idintegerrequired
- source_revisionintegerrequired
- statusstringrequiredOne of: draft, approved, posted, reversed, cancelled.
- prepared_by_idintegerrequired
- contributor_idsinteger[]required
- approved_by_idinteger | nullrequired
- approved_atstring (date-time) | nullrequired
- journal_entry_idinteger | nullrequired
- corrects_receipt_idinteger | nullrequired
- reversalobject | nullrequired
- reversal.idintegerrequired
- reversal.source_revisionintegerrequired
- reversal.posting_datestring (date)required
- reversal.reasonstringrequired
- reversal.journal_entry_idintegerrequired
- reversal.actor_user_idintegerrequired
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].invoice_idintegerrequired
- applications[].invoice_revisionintegerrequired
- applications[].journal_line_idintegerrequired
- applications[].bucketstringrequiredOne of: current, retainage.
- applications[].amountstringrequiredNegative only on the from-side of a transfer.
- applications[].cash_application_idinteger | nullNull for allocations made at entry.
- cancellation_reasonstring | nullrequired
- methodstringOne of: check, ach, wire, card, cash, other.
- check_nostring | null
- payerstring | null
- unapplied_amountstringCash still held in CUSTOMER_DEPOSITS (entry remainder less later applications).
Errors
401Authentication required403Scope or separation of duties denied404Scoped source not found409State, revision, overapplication or idempotency conflict422Invalid data, dates, account or closed period
Example request
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/receiptsRecord 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.
Parameters
- company_idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- request_keystring (uuid)required
- receiptobjectrequired
- receipt.entity_idintegerrequired
- receipt.customer_idintegerrequired
- receipt.cash_account_idintegerrequired
- receipt.referencestringrequired
- receipt.posting_datestring (date)required
- receipt.amountstringrequired
- receipt.applicationsobject[]requiredAllocations at entry; any remainder of amount posts to CUSTOMER_DEPOSITS as unapplied cash.
- receipt.applications[].invoice_idintegerrequired
- receipt.applications[].invoice_revisionintegerrequired
- receipt.applications[].journal_line_idintegerrequired
- receipt.applications[].bucketstringrequiredOne of: current, retainage.
- receipt.applications[].amountstringrequired
- receipt.correctionobject | null
- receipt.correction.receipt_idintegerrequired
- receipt.correction.revisionintegerrequired
- receipt.methodstringOne of: check, ach, wire, card, cash, other.
- receipt.check_nostring | null
- receipt.payerstring | null
Response · 201 · object
- idintegerrequired
- numberstringrequired
- entity_idintegerrequired
- customer_idintegerrequired
- referencestringrequired
- posting_datestring (date)required
- currencystringrequired
- amountstringrequired
- cash_account_idintegerrequired
- revisionintegerrequired
- source_typestringrequired
- source_idintegerrequired
- source_revisionintegerrequired
- statusstringrequiredOne of: draft, approved, posted, reversed, cancelled.
- prepared_by_idintegerrequired
- contributor_idsinteger[]required
- approved_by_idinteger | nullrequired
- approved_atstring (date-time) | nullrequired
- journal_entry_idinteger | nullrequired
- corrects_receipt_idinteger | nullrequired
- reversalobject | nullrequired
- reversal.idintegerrequired
- reversal.source_revisionintegerrequired
- reversal.posting_datestring (date)required
- reversal.reasonstringrequired
- reversal.journal_entry_idintegerrequired
- reversal.actor_user_idintegerrequired
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].invoice_idintegerrequired
- applications[].invoice_revisionintegerrequired
- applications[].journal_line_idintegerrequired
- applications[].bucketstringrequiredOne of: current, retainage.
- applications[].amountstringrequiredNegative only on the from-side of a transfer.
- applications[].cash_application_idinteger | nullNull for allocations made at entry.
- cancellation_reasonstring | nullrequired
- methodstringOne of: check, ach, wire, card, cash, other.
- check_nostring | null
- payerstring | null
- unapplied_amountstringCash still held in CUSTOMER_DEPOSITS (entry remainder less later applications).
Errors
400Malformed JSON request body401Authentication required403Scope or separation of duties denied404Scoped source not found409State, revision, overapplication or idempotency conflict422Invalid data, dates, account or closed period
Example request
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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- entity_idintegerrequired
- customer_idintegerrequired
- referencestringrequired
- posting_datestring (date)required
- currencystringrequired
- amountstringrequired
- cash_account_idintegerrequired
- revisionintegerrequired
- source_typestringrequired
- source_idintegerrequired
- source_revisionintegerrequired
- statusstringrequiredOne of: draft, approved, posted, reversed, cancelled.
- prepared_by_idintegerrequired
- contributor_idsinteger[]required
- approved_by_idinteger | nullrequired
- approved_atstring (date-time) | nullrequired
- journal_entry_idinteger | nullrequired
- corrects_receipt_idinteger | nullrequired
- reversalobject | nullrequired
- reversal.idintegerrequired
- reversal.source_revisionintegerrequired
- reversal.posting_datestring (date)required
- reversal.reasonstringrequired
- reversal.journal_entry_idintegerrequired
- reversal.actor_user_idintegerrequired
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].invoice_idintegerrequired
- applications[].invoice_revisionintegerrequired
- applications[].journal_line_idintegerrequired
- applications[].bucketstringrequiredOne of: current, retainage.
- applications[].amountstringrequiredNegative only on the from-side of a transfer.
- applications[].cash_application_idinteger | nullNull for allocations made at entry.
- cancellation_reasonstring | nullrequired
- methodstringOne of: check, ach, wire, card, cash, other.
- check_nostring | null
- payerstring | null
- unapplied_amountstringCash still held in CUSTOMER_DEPOSITS (entry remainder less later applications).
Errors
401Authentication required403Scope or separation of duties denied404Scoped source not found409State, revision, overapplication or idempotency conflict422Invalid data, dates, account or closed period
Example request
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}/applicationsApply 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- request_keystring (uuid)required
- kindstringrequiredapply: 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_datestring (date)required
- applicationsobject[]required
- applications[].invoice_idintegerrequired
- applications[].invoice_revisionintegerrequired
- applications[].journal_line_idintegerrequired
- applications[].bucketstringrequiredOne of: current, retainage.
- applications[].amountstringrequired
Response · 201 · object
- idinteger
- receipt_idinteger
- kindstringOne of: apply, transfer.
- posting_datestring (date)
- journal_entry_idinteger
- actor_user_idinteger
- applicationsobject[]
- applications[].idinteger
- applications[].invoice_idinteger
- applications[].journal_line_idinteger
- applications[].bucketstring
- applications[].amountstring
Errors
400Malformed JSON request body401Authentication required403Scope or separation of duties denied404Scoped source not found409State, revision, overapplication or idempotency conflict422Invalid data, dates, account or closed period
Example request
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}/attachmentsList attachments on a AR receipt
Oldest first. Needs view_ledger and the parent's entity scope. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object[]
- idintegerrequired
- doc_typestringrequiredOne of: journal_entry, ap_bill, vendor, ap_compliance, ap_lien_waiver, ar_invoice, ar_receipt, bank_transaction, fixed_asset, wip_snapshot, account_rec, policy_signoff.
- doc_idintegerrequired
- namestringrequired
- content_typestringrequired
- size_bytesintegerrequired
- sha256stringrequired
- uploaded_byobjectrequired
- uploaded_by.idintegerrequired
- uploaded_by.namestring | nullrequired
- created_atstring (date-time)required
- download_urlstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ar/receipts/1/attachments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Receivable
POST/rest/v1.0/companies/{company_id}/accounting/ar/receipts/{id}/attachmentsAttach 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- filestring (binary)required
Response · 201 · object
- idintegerrequired
- doc_typestringrequiredOne of: journal_entry, ap_bill, vendor, ap_compliance, ap_lien_waiver, ar_invoice, ar_receipt, bank_transaction, fixed_asset, wip_snapshot, account_rec, policy_signoff.
- doc_idintegerrequired
- namestringrequired
- content_typestringrequired
- size_bytesintegerrequired
- sha256stringrequired
- uploaded_byobjectrequired
- uploaded_by.idintegerrequired
- uploaded_by.namestring | nullrequired
- created_atstring (date-time)required
- download_urlstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace404Not found in this company409Idempotency-Key reused for a different request or still in progress413Request body too large422Missing file, empty file, too large, or a type that is not allowed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/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}/reverseAppend 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- request_keystring (uuid)required
- revisionintegerrequired
- datestring (date)required
- reasonstringrequired
- nsfbooleanReceipt 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
- idintegerrequired
- source_revisionintegerrequired
- posting_datestring (date)required
- reasonstringrequired
- journal_entry_idintegerrequired
- actor_user_idintegerrequired
Errors
400Malformed JSON request body401Authentication required403Scope or separation of duties denied404Scoped source not found409State, revision, overapplication or idempotency conflict422Invalid data, dates, account or closed period
Example request
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}/transitionIndependently 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- revisionintegerrequired
- actionstringrequiredOne of: approve, post, cancel.
- reasonstring
Response · 200 · object
- idintegerrequired
- numberstringrequired
- entity_idintegerrequired
- customer_idintegerrequired
- referencestringrequired
- posting_datestring (date)required
- currencystringrequired
- amountstringrequired
- cash_account_idintegerrequired
- revisionintegerrequired
- source_typestringrequired
- source_idintegerrequired
- source_revisionintegerrequired
- statusstringrequiredOne of: draft, approved, posted, reversed, cancelled.
- prepared_by_idintegerrequired
- contributor_idsinteger[]required
- approved_by_idinteger | nullrequired
- approved_atstring (date-time) | nullrequired
- journal_entry_idinteger | nullrequired
- corrects_receipt_idinteger | nullrequired
- reversalobject | nullrequired
- reversal.idintegerrequired
- reversal.source_revisionintegerrequired
- reversal.posting_datestring (date)required
- reversal.reasonstringrequired
- reversal.journal_entry_idintegerrequired
- reversal.actor_user_idintegerrequired
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].invoice_idintegerrequired
- applications[].invoice_revisionintegerrequired
- applications[].journal_line_idintegerrequired
- applications[].bucketstringrequiredOne of: current, retainage.
- applications[].amountstringrequiredNegative only on the from-side of a transfer.
- applications[].cash_application_idinteger | nullNull for allocations made at entry.
- cancellation_reasonstring | nullrequired
- methodstringOne of: check, ach, wire, card, cash, other.
- check_nostring | null
- payerstring | null
- unapplied_amountstringCash still held in CUSTOMER_DEPOSITS (entry remainder less later applications).
Errors
400Malformed JSON request body401Authentication required403Scope or separation of duties denied404Scoped source not found409State, revision, overapplication or idempotency conflict422Invalid data, dates, account or closed period
Example request
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_itemsOpen 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.
Parameters
- company_idintegerpathrequired
- entity_idintegerqueryrequired
- customer_idintegerqueryrequired
- pageintegerquery
- per_pageintegerquery
- currencystringqueryReceipt 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
- totalintegerrequired
- currencystringrequired
- accountsobject[]required
- accounts[].idintegerrequired
- accounts[].numberstringrequired
- accounts[].namestringrequired
- itemsobject[]required
- items[].invoice_idintegerrequired
- items[].invoice_numberstringrequired
- items[].due_datestring (date)required
- items[].invoice_revisionintegerrequired
- items[].journal_line_idintegerrequired
- items[].bucketstringrequiredOne of: current, retainage.
- items[].descriptionstring | nullrequired
- items[].project_idinteger | nullrequired
- items[].openstringrequired
- per_pageintegerrequired
Errors
401Authentication required403Scope or separation of duties denied404Scoped source not found409State, revision, overapplication or idempotency conflict422Invalid data, dates, account or closed period
Example request
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/refundsCustomer refunds, newest first (paginated).
Refunds in the caller's entities; project-scoped grants are refused. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequired
- customer_idintegerquery
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- idintegerrequired
- numberstringrequired
- entity_idintegerrequired
- customer_idintegerrequired
- receipt_idinteger | null
- credit_memo_idinteger | null
- amountstringrequired
- currencystring
- bank_account_idinteger
- posting_datestring (date)required
- methodstring
- referencestring | null
- memostring | null
- statusstringrequiredOne of: draft, posted, cancelled, reversed.
- prepared_by_idinteger
- approved_by_idinteger | null
- approved_atstring | null (date-time)
- journal_entry_idinteger | null
- reasonstring | null
- reversal_entry_idinteger | null
- reversal_datestring | null (date)
Errors
401Authentication required403Scope or separation of duties denied404Scoped source not found
Example request
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/refundsDraft 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.
Parameters
- company_idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- request_keystring (uuid)required
- refundobjectrequiredExactly one of receipt_id (its unapplied cash) or credit_memo_id (an on-account credit memo).
- refund.receipt_idinteger | null
- refund.credit_memo_idinteger | null
- refund.bank_account_idintegerrequired
- refund.posting_datestring (date)required
- refund.amountstringrequired
- refund.methodstringOne of: check, ach, wire, card, cash, other.
- refund.referencestring | null
- refund.memostring | null
Response · 201 · object
- idintegerrequired
- numberstringrequired
- entity_idintegerrequired
- customer_idintegerrequired
- receipt_idinteger | null
- credit_memo_idinteger | null
- amountstringrequired
- currencystring
- bank_account_idinteger
- posting_datestring (date)required
- methodstring
- referencestring | null
- memostring | null
- statusstringrequiredOne of: draft, posted, cancelled, reversed.
- prepared_by_idinteger
- approved_by_idinteger | null
- approved_atstring | null (date-time)
- journal_entry_idinteger | null
- reasonstring | null
- reversal_entry_idinteger | null
- reversal_datestring | null (date)
Errors
400Malformed JSON request body401Authentication required403Scope or separation of duties denied404Scoped source not found409State, revision, overapplication or idempotency conflict422Invalid data, dates, account or closed period
Example request
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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- entity_idintegerrequired
- customer_idintegerrequired
- receipt_idinteger | null
- credit_memo_idinteger | null
- amountstringrequired
- currencystring
- bank_account_idinteger
- posting_datestring (date)required
- methodstring
- referencestring | null
- memostring | null
- statusstringrequiredOne of: draft, posted, cancelled, reversed.
- prepared_by_idinteger
- approved_by_idinteger | null
- approved_atstring | null (date-time)
- journal_entry_idinteger | null
- reasonstring | null
- reversal_entry_idinteger | null
- reversal_datestring | null (date)
Errors
401Authentication required403Scope or separation of duties denied404Scoped source not found
Example request
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}/transitionPost, 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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- actionstringrequiredOne of: post, cancel, reverse.
- reasonstringRequired to cancel or reverse.
- datestring (date)Reversal date (reverse only).
Response · 200 · object
- idintegerrequired
- numberstringrequired
- entity_idintegerrequired
- customer_idintegerrequired
- receipt_idinteger | null
- credit_memo_idinteger | null
- amountstringrequired
- currencystring
- bank_account_idinteger
- posting_datestring (date)required
- methodstring
- referencestring | null
- memostring | null
- statusstringrequiredOne of: draft, posted, cancelled, reversed.
- prepared_by_idinteger
- approved_by_idinteger | null
- approved_atstring | null (date-time)
- journal_entry_idinteger | null
- reasonstring | null
- reversal_entry_idinteger | null
- reversal_datestring | null (date)
Errors
400Malformed JSON request body401Authentication required403Scope or separation of duties denied404Scoped source not found409State, revision, overapplication or idempotency conflict422Invalid data, dates, account or closed period
Example request
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"
}'