Finance Operations API reference · mansoq-core

Declared route and availability

This resource is declared in mansoq-core at /api/v1/facility/{facility_external_id}/rcm/finance/. verified core mount in config/urls.py A registered path and an indexed handler do not prove deployment availability, user permission or production readiness.

SET-12: the six finance actions, with their balance identities visible.

Operation map

list · GET

GET /api/v1/facility/{facility_external_id}/rcm/finance/ — action list. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: PermissionDenied: Cannot read revenue-cycle records.

retrieve · GET

GET /api/v1/facility/{facility_external_id}/rcm/finance/{external_id}/ — action retrieve. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: PermissionDenied: Cannot read revenue-cycle records.

actions · GET

The six SET-12 actions, and the documented responsibility for each.

GET /api/v1/facility/{facility_external_id}/rcm/finance/actions/ — action actions. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: PermissionDenied: Cannot read revenue-cycle records.

balance_identities · GET

Both ledgers' conservation checks, rendered separately.

GET /api/v1/facility/{facility_external_id}/rcm/finance/{external_id}/balance-identities/ — action balance_identities. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: PermissionDenied: Cannot read revenue-cycle records.

claim_identity · GET

The per-claim identity a biller reads before issuing anything.

GET /api/v1/facility/{facility_external_id}/rcm/finance/claim-identity/ — action claim_identity. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: PermissionDenied: Cannot read revenue-cycle records; ValidationError (dynamic detail; inspect source); ValidationError: claim is required.

variance · POST

Attribute the gap between a reported advice and a confirmed credit.

Each candidate explanation carries the sign configuration gives it, and whatever remains is reported as unexplained rather than absorbed.

POST /api/v1/facility/{facility_external_id}/rcm/finance/{external_id}/variance/ — action variance. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: PermissionDenied: Cannot read revenue-cycle records.

reconcile · POST

Record one payment reconciliation and its allocations, exactly once.

An unmatched line goes to advice suspense with its losing candidates named. It is never attached to the nearest plausible claim: a wrong match is harder to find later than an unmatched line.

POST /api/v1/facility/{facility_external_id}/rcm/finance/reconcile/ — action reconcile. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_manage_rcm_claims_in_facility, can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Explicit response statuses in observed code: dynamic status. Other branches/framework exception handling may differ.

Declared refusal/error evidence: PermissionDenied: Cannot submit, adjudicate or settle claims; ValidationError: config_package_missing; A financial decision writes exactly one trace referencing its configuration package. None is published for this facility.; ValidationError: config_package_not_found; PermissionDenied: Cannot read revenue-cycle records.

cash_receipt · POST

Import a bank credit; treasury separately confirms return status.

POST /api/v1/facility/{facility_external_id}/rcm/finance/cash-receipt/ — action cash_receipt. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_manage_rcm_cash_in_facility, can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Explicit response statuses in observed code: 201. Other branches/framework exception handling may differ.

Declared refusal/error evidence: ValidationError: bank_account does not exist for this facility; PermissionDenied: Cannot manage bank cash; PermissionDenied: Cannot read revenue-cycle records.

confirm_bank_receipt · POST

Record treasury's audited bank-statement confirmation.

A payment notice cannot be sent while return status is unknown. The confirmation must name the exact statement line recorded at import.

POST /api/v1/facility/{facility_external_id}/rcm/finance/confirm-bank-receipt/ — action confirm_bank_receipt. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_confirm_rcm_bank_receipt_in_facility, can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: PermissionDenied: Cannot confirm a bank receipt; ValidationError: bank_transaction does not exist for this facility; PermissionDenied: Cannot read revenue-cycle records.

settle · POST

Distribute one bank transaction across advices, claims and suspense.

POST /api/v1/facility/{facility_external_id}/rcm/finance/settle/ — action settle. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_manage_rcm_cash_in_facility, can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Explicit response statuses in observed code: 201. Other branches/framework exception handling may differ.

Declared refusal/error evidence: PermissionDenied: Cannot manage bank cash; ValidationError: config_package_missing; A financial decision writes exactly one trace referencing its configuration package. None is published for this facility.; ValidationError: config_package_not_found; ValidationError: bank_transaction does not exist for this facility; PermissionDenied: Cannot read revenue-cycle records; ValidationError: advice does not exist for this facility; ValidationError (dynamic detail; inspect source); ValidationError: claim is required.

payment_notice · POST

Notify the payer — only after the money is in the provider's account.

A notice is a regulator-visible bank-reconciliation obligation. Sending one before the credit is confirmed asserts something untrue.

POST /api/v1/facility/{facility_external_id}/rcm/finance/payment-notice/ — action payment_notice. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_manage_rcm_cash_in_facility, can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Explicit response statuses in observed code: dynamic status. Other branches/framework exception handling may differ.

Declared refusal/error evidence: PermissionDenied: Cannot manage bank cash; ValidationError: advice does not exist for this facility; ValidationError: bank_transaction does not exist for this facility; PermissionDenied: Cannot read revenue-cycle records.

reverse · POST

Post a compensating entry. Nothing is edited and nothing is deleted.

Idempotent by design: a repeated reversal reports already_reversed rather than posting a second one, so an unattended retry is harmless.

POST /api/v1/facility/{facility_external_id}/rcm/finance/reverse/ — action reverse. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_manage_rcm_cash_in_facility, can_manage_rcm_claims_in_facility, can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Explicit response statuses in observed code: dynamic status. Other branches/framework exception handling may differ.

Declared refusal/error evidence: ValidationError: ledger must be 'advice' or 'cash'; ValidationError: allocation does not exist for this facility; ValidationError: reason is required; a reversal explains itself; ValidationError: config_package_missing; A financial decision writes exactly one trace referencing its configuration package. None is published for this facility.; ValidationError: config_package_not_found; PermissionDenied: Cannot manage bank cash; PermissionDenied: Cannot submit, adjudicate or settle claims; PermissionDenied: Cannot read revenue-cycle records.

returned_payment · POST

Flag a bank credit returned and reverse everything that rested on it.

POST /api/v1/facility/{facility_external_id}/rcm/finance/returned-payment/ — action returned_payment. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_manage_rcm_cash_in_facility, can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: PermissionDenied: Cannot manage bank cash; ValidationError: bank_transaction does not exist for this facility; ValidationError: config_package_missing; A financial decision writes exactly one trace referencing its configuration package. None is published for this facility.; ValidationError: config_package_not_found; PermissionDenied: Cannot read revenue-cycle records.

estimate · POST

Quote what may lawfully be asked of the patient — or refuse to quote.

SET-12's first action. FINANCE_ACTIONS publishes six and this screen has to answer for all six; without this one a client reading the catalogue finds five endpoints behind six names.

It posts nothing. The estimate is built by the same engine the liability surface uses, so the five mandatory facts (verification time, assumptions, unresolved benefits, expiry, certainty) are enforced by one rule rather than two, and it is returned beside the claim's balance identity so a quote is visibly a quote and not the identity itself.

POST /api/v1/facility/{facility_external_id}/rcm/finance/estimate/ — action estimate. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: PermissionDenied: Cannot read revenue-cycle records; ValidationError (dynamic detail; inspect source); ValidationError: claim is required.

issue · POST

Issue a patient balance — never the provider's contractual shortfall.

Only patient_receivable determinations with a named reviewer are billable. Contractual adjustments are returned alongside, explicitly not billable, and a request that asks to include them is refused rather than warned about.

POST /api/v1/facility/{facility_external_id}/rcm/finance/issue/ — action issue. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_manage_rcm_claims_in_facility, can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: ValidationError: contractual_shortfall_not_billable; A provider contractual shortfall is never transferred to the patient. It cannot be included in an issued balance.; ValidationError: named_reviewer_required; Some amounts are marked patient_receivable with no named reviewer. Name one, or leave them with the payer.; PermissionDenied: Cannot submit, adjudicate or settle claims; ValidationError (dynamic detail; inspect source); ValidationError: claim is required; PermissionDenied: Cannot read revenue-cycle records.

credit · POST

The three-case insurer-rejection credit-note taxonomy, as data.

Gate CF-U20 is open: the taxonomy is held as configuration carrying its own evidence, not resolved in code. The response names the gate and the matching case rather than deciding the accounting treatment.

POST /api/v1/facility/{facility_external_id}/rcm/finance/credit/ — action credit. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_manage_rcm_claims_in_facility, can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: PermissionDenied: Cannot submit, adjudicate or settle claims; PermissionDenied: Cannot read revenue-cycle records.

refund · POST

Refund a traceable credit. Maker-checker applies, always.

Report ch. 31 names refunds among the four categories that require an approver who is not the author, and the engine refuses a refund that cannot name its recipient, its reference and its approver.

POST /api/v1/facility/{facility_external_id}/rcm/finance/refund/ — action refund. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_manage_rcm_claims_in_facility, can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Explicit response statuses in observed code: 201. Other branches/framework exception handling may differ.

Declared refusal/error evidence: PermissionDenied: Cannot submit, adjudicate or settle claims; ValidationError: patient is required; ValidationError (dynamic detail; inspect source); ValidationError: claim is required; PermissionDenied: Cannot read revenue-cycle records.

aging · POST

Age and provision receivables per payer class. No blended total.

unclassified keeps its own cohort and takes no provision; it is a statement that the payer class has not been established, not a fifth bucket to be averaged away.

POST /api/v1/facility/{facility_external_id}/rcm/finance/aging/ — action aging. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: PermissionDenied: Cannot read revenue-cycle records; ValidationError: aging_policy_unresolved; No active receivable aging policy. The anchor basis and the buckets are configuration; they are never defaulted.; ValidationError: minor_units_unresolved; minor_units is a property of the currency being aged and is not defaulted. Send the minor units for this currency.; ValidationError (dynamic detail; inspect source).

suspense · GET

Unmatched advice lines and cash with no payment notice behind it.

Both are queues with owners, an aging policy and an escalation path, so the owning queues travel with the rows.

GET /api/v1/facility/{facility_external_id}/rcm/finance/suspense/ — action suspense. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: PermissionDenied: Cannot read revenue-cycle records.

accounting_manifest · POST

Freeze the exact remittance/cash ledger rows handed to accounting.

This is the controlled boundary before an ERP/GL connector. It does not invent a journal inside RCM and it does not net advice with cash; it signs the rows, totals and source identifiers that the accounting interface is allowed to consume exactly once.

POST /api/v1/facility/{facility_external_id}/rcm/finance/accounting-manifest/ — action accounting_manifest. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_manage_rcm_cash_in_facility, can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Explicit response statuses in observed code: dynamic status. Other branches/framework exception handling may differ.

Declared refusal/error evidence: PermissionDenied: Cannot manage bank cash; ValidationError: config_package_missing; A financial decision writes exactly one trace referencing its configuration package. None is published for this facility.; ValidationError: config_package_not_found; PermissionDenied: Cannot read revenue-cycle records.

accounting_export_payload · POST

Prepare the deterministic payload an ERP connector may post.

POST /api/v1/facility/{facility_external_id}/rcm/finance/accounting-export-payload/ — action accounting_export_payload. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_manage_rcm_cash_in_facility, can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Explicit response statuses in observed code: dynamic status. Other branches/framework exception handling may differ.

Declared refusal/error evidence: PermissionDenied: Cannot manage bank cash; ValidationError: manifest is required; ValidationError: Unknown accounting manifest for this facility; PermissionDenied: Cannot read revenue-cycle records.

accounting_export_ack · POST

Record the downstream ERP/GL response for a prepared payload.

POST /api/v1/facility/{facility_external_id}/rcm/finance/accounting-export-ack/ — action accounting_export_ack. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_manage_rcm_cash_in_facility, can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Explicit response statuses in observed code: 200. Other branches/framework exception handling may differ.

Declared refusal/error evidence: PermissionDenied: Cannot manage bank cash; PermissionDenied: Cannot read revenue-cycle records.

accounting_close_readiness · GET

Tell finance exactly why a settlement period can or cannot close.

GET /api/v1/facility/{facility_external_id}/rcm/finance/accounting-close-readiness/ — action accounting_close_readiness. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_manage_rcm_cash_in_facility, can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: PermissionDenied: Cannot manage bank cash; PermissionDenied: Cannot read revenue-cycle records.

accounting_close · POST

Create the immutable accounting period-close certificate.

POST /api/v1/facility/{facility_external_id}/rcm/finance/accounting-close/ — action accounting_close. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_manage_rcm_cash_in_facility, can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Explicit response statuses in observed code: dynamic status. Other branches/framework exception handling may differ.

Declared refusal/error evidence: PermissionDenied: Cannot manage bank cash; PermissionDenied: Cannot read revenue-cycle records.

bank_accounts · GET

Settlement accounts, masked, with their dual-control state.

GET /api/v1/facility/{facility_external_id}/rcm/finance/bank-accounts/ — action bank_accounts. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: PermissionDenied: Cannot read revenue-cycle records.

bank_account_change · POST

Record a bank-detail change: dual control plus independent verification.

Three distinct people, and an immutable review item as the output. The service writes the audit event; this endpoint exists so the three cannot be collapsed into "the finance manager ticked it".

POST /api/v1/facility/{facility_external_id}/rcm/finance/bank-account-change/ — action bank_account_change. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_manage_rcm_claims_in_facility, can_read_account_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Explicit response statuses in observed code: 201. Other branches/framework exception handling may differ.

Declared refusal/error evidence: ValidationError: bank_account does not exist for this facility; ValidationError: verification_note is required; the verification is written down.; PermissionDenied: Cannot submit, adjudicate or settle claims; PermissionDenied: Cannot read revenue-cycle records.

Integration review checklist

Confirm the installed route and full schema; review authentication, organization/facility scoping, all accepted fields, value-state and date/time semantics, idempotency, pagination, response/exception branches and the allowed correction/reversal workflow. Test positive and negative cases with synthetic data. This source reference does not establish external certification or replace an illustrated user procedure.