← Technical API reference

Backend resource · STATIC DECLARATIONS

Patient Liability API reference · mansoq-core

Static source contract for Patient Liability: 15 declared or inherited operation mappings, schema/field evidence and authorization/refusal references. Deployment and behavioral review remain explicit.

Static API contract — behavior review pending. Source baseline f6e9f05f76d4.

Enable JavaScript to inspect structured operation, parameter, schema and permission evidence. Download this reference and its evidence.

Declared route and availability

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

Collectable patient debt and unresolved insurance shortfall, side by side.

Operation map

Method Path Action Evidence
GET /api/v1/facility/{facility_external_id}/rcm/liability/ list declared/inherited method
GET /api/v1/facility/{facility_external_id}/rcm/liability/{external_id}/ retrieve declared/inherited method
GET /api/v1/facility/{facility_external_id}/rcm/liability/position/ position @action declaration
POST /api/v1/facility/{facility_external_id}/rcm/liability/evaluate/ evaluate @action declaration
POST /api/v1/facility/{facility_external_id}/rcm/liability/decide/ decide @action declaration
POST /api/v1/facility/{facility_external_id}/rcm/liability/{external_id}/transfer/ transfer @action declaration
POST /api/v1/facility/{facility_external_id}/rcm/liability/estimate/ estimate @action declaration
POST /api/v1/facility/{facility_external_id}/rcm/liability/{external_id}/acknowledge/ acknowledge @action declaration
GET /api/v1/facility/{facility_external_id}/rcm/liability/undertakings/ undertakings @action declaration
POST /api/v1/facility/{facility_external_id}/rcm/liability/deposit/ deposit @action declaration
POST /api/v1/facility/{facility_external_id}/rcm/liability/reconcile-deposit/ reconcile_deposit @action declaration
POST /api/v1/facility/{facility_external_id}/rcm/liability/upgrade/ upgrade @action declaration
POST /api/v1/facility/{facility_external_id}/rcm/liability/copayment/ copayment @action declaration
POST /api/v1/facility/{facility_external_id}/rcm/liability/{external_id}/write-off/ write_off @action declaration
POST /api/v1/facility/{facility_external_id}/rcm/liability/{external_id}/write-off-reversal/ write_off_reversal @action declaration

list · GET

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

Path and deployment-context parameters:

Location Parameter Type Required
path facility_external_id router lookup string; semantic ID validation requires handler/schema review true

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

Location Field Declared/inferred read type Requiredness evidence
query patient not declared at read site not established
query claim not declared at read site not established
query {computed field name} not declared at read site not established

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/liability/{external_id}/ — action retrieve. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Location Parameter Type Required
path facility_external_id router lookup string; semantic ID validation requires handler/schema review true
path external_id router lookup string; semantic ID validation requires handler/schema review true

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

Location Field Declared/inferred read type Requiredness evidence
query patient not declared at read site not established
query claim not declared at read site not established
query {computed field name} not declared at read site not established

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.

position · GET

The one screen: two totals, computed apart and never added.

collectable_patient_debt is what the cashier can pursue. unresolved_insurance_shortfall is what the appeals desk must pursue with the payer. There is deliberately no combined figure: a blended "outstanding" number is how a provider contractual shortfall becomes a patient statement line.

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

Path and deployment-context parameters:

Location Parameter Type Required
path facility_external_id router lookup string; semantic ID validation requires handler/schema review true

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

Location Field Declared/inferred read type Requiredness evidence
query patient not declared at read site not established
query claim not declared at read site not established
query {computed field name} not declared at read site not established

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.

evaluate · POST

Decide the basis and disposition of one amount. Posts nothing.

The candidate list comes back whole — every basis considered and why it was or was not admitted — so an operator can see that unresolved was a refusal to guess rather than an absence of logic.

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

Path and deployment-context parameters:

Location Parameter Type Required
path facility_external_id router lookup string; semantic ID validation requires handler/schema review true

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

Location Field Declared/inferred read type Requiredness evidence
query patient not declared at read site not established
query claim not declared at read site not established
query {computed field name} not declared at read site not established

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.

decide · POST

Record one liability determination and exactly one decision trace.

A move to patient_receivable is refused without a named reviewer — here, before the engine is called, so the error names the missing field rather than surfacing as an engine refusal the UI cannot act on.

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

Path and deployment-context parameters:

Location Parameter Type Required
path facility_external_id router lookup string; semantic ID validation requires handler/schema review true

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

Location Field Declared/inferred read type Requiredness evidence
body requested_disposition not declared at read site not established
body reviewer reviewer reference helper default; inspect declaration
body patient not declared at read site not established
body claim not declared at read site not established
body claim_line not declared at read site not established
body reviewed_at timezone-aware datetime false
body config_package not declared at read site not established
query patient not declared at read site not established
query claim not declared at read site not established
query {computed field name} not declared at read site not established

Observed authorization checks: can_update_account_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 update revenue-cycle records; ValidationError: patient is required; ValidationError (dynamic detail; inspect source); ValidationError: claim_line requires its claim; ValidationError: config_package_missing; A liability determination 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.

transfer · POST

Move an existing determination to patient_receivable.

Refused without a named reviewer, and refused outright where the basis cannot carry collectable debt. A contractual adjustment is the provider's own shortfall; it has no patient path at all.

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

Path and deployment-context parameters:

Location Parameter Type Required
path facility_external_id router lookup string; semantic ID validation requires handler/schema review true
path external_id router lookup string; semantic ID validation requires handler/schema review true

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

Location Field Declared/inferred read type Requiredness evidence
body reviewer reviewer reference helper default; inspect declaration
body reviewed_at timezone-aware datetime false
query patient not declared at read site not established
query claim not declared at read site not established
query {computed field name} not declared at read site not established

Observed authorization checks: can_update_account_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: basis_not_collectable; ValidationError: contractual_shortfall_not_transferable; A contractual adjustment is the provider's own shortfall. It is never transferred to the patient.; PermissionDenied: Cannot update revenue-cycle records; PermissionDenied: Cannot read revenue-cycle records.

estimate · POST

Build a presentable estimate, or refuse to present one.

Five facts are mandatory: the payer-verification time, at least one assumption, the unresolved benefits (possibly an explicit empty list), the expiry and the certainty flag. Without them the engine raises rather than quoting a number that looks firmer than it is.

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

Path and deployment-context parameters:

Location Parameter Type Required
path facility_external_id router lookup string; semantic ID validation requires handler/schema review true

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

Location Field Declared/inferred read type Requiredness evidence
body amount Decimal helper default; inspect declaration
body currency not declared at read site not established
body payer_verified_at timezone-aware datetime false
body expires_on date false
body certainty not declared at read site not established
body assumptions not declared at read site not established
body unresolved_benefits not declared at read site not established
query patient not declared at read site not established
query claim not declared at read site not established
query {computed field name} not declared at read site not established

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.

acknowledge · POST

Record an acknowledgment for a permitted estimate or an election.

Nothing else is acknowledgeable. A blanket commitment to pay whatever the insurer later rejects is prohibited outright, and so is the cash-then- refund workaround — so there is no template, no flag and no free-text field here that can carry one.

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

Path and deployment-context parameters:

Location Parameter Type Required
path facility_external_id router lookup string; semantic ID validation requires handler/schema review true
path external_id router lookup string; semantic ID validation requires handler/schema review true

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

Location Field Declared/inferred read type Requiredness evidence
body subject not declared at read site not established
body undertaking not declared at read site direct indexing; validation may be upstream
body estimate_reference not declared at read site not established
body plan_explained not declared at read site not established
body coverage_explained not declared at read site not established
body plan_exceeds_benefit_limits not declared at read site not established
query patient not declared at read site not established
query claim not declared at read site not established
query {computed field name} not declared at read site not established

Observed authorization checks: can_update_account_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: acknowledgment_subject_not_permitted; An acknowledgment may be taken for a permitted estimate or an elected noncovered service. It is never a blanket consent to future rejections.; PermissionDenied: Cannot update revenue-cycle records; PermissionDenied: Cannot read revenue-cycle records.

undertakings · GET

The whole lawful set of pre-treatment undertakings — and the rest.

Publishing the prohibited kinds by name is the point: they exist in the vocabulary so that a request carrying one is refused rather than silently accepted as free text.

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

Path and deployment-context parameters:

Location Parameter Type Required
path facility_external_id router lookup string; semantic ID validation requires handler/schema review true

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

Location Field Declared/inferred read type Requiredness evidence
query patient not declared at read site not established
query claim not declared at read site not established
query {computed field name} not declared at read site not established

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.

deposit · POST

Hold money. A deposit is not a settled charge and changes no disposition.

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

Path and deployment-context parameters:

Location Parameter Type Required
path facility_external_id router lookup string; semantic ID validation requires handler/schema review true

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

Location Field Declared/inferred read type Requiredness evidence
body amount Decimal helper default; inspect declaration
body currency not declared at read site not established
body requested_disposition_change not declared at read site not established
body received_on date false
body payment_reference not declared at read site not established
body liability_decision_id not declared at read site not established
body patient not declared at read site not established
body claim not declared at read site not established
query patient not declared at read site not established
query claim not declared at read site not established
query {computed field name} not declared at read site not established

Observed authorization checks: can_update_account_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 update revenue-cycle records; ValidationError: patient is required; ValidationError (dynamic detail; inspect source); PermissionDenied: Cannot read revenue-cycle records.

reconcile_deposit · POST

Reconcile held money against the liability actually permitted.

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

Path and deployment-context parameters:

Location Parameter Type Required
path facility_external_id router lookup string; semantic ID validation requires handler/schema review true

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

Location Field Declared/inferred read type Requiredness evidence
body deposit_amount Decimal helper default; inspect declaration
body permitted_liability_amount Decimal helper default; inspect declaration
body currency not declared at read site not established
query patient not declared at read site not established
query claim not declared at read site not established
query {computed field name} not declared at read site not established

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.

upgrade · POST

Price an elected upgrade as two lines: entitlement and increment.

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

Path and deployment-context parameters:

Location Parameter Type Required
path facility_external_id router lookup string; semantic ID validation requires handler/schema review true

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

Location Field Declared/inferred read type Requiredness evidence
body amount Decimal helper default; inspect declaration
body currency not declared at read site not established
body payer_verified_at timezone-aware datetime false
body expires_on date false
body certainty not declared at read site not established
body total_elected_amount Decimal helper default; inspect declaration
body covered_entitlement_amount Decimal helper default; inspect declaration
body covered_entitlement_state not declared at read site not established
body covered_alternative_disclosed not declared at read site not established
body assumptions not declared at read site not established
body unresolved_benefits not declared at read site not established
query patient not declared at read site not established
query claim not declared at read site not established
query {computed field name} not declared at read site not established

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.

copayment · POST

Both edges of the co-payment: under-collection and over-collection.

Under-collection is a claim-validity risk; over-collection is prohibited. A design that watches only one of them fails, so both are returned.

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

Path and deployment-context parameters:

Location Parameter Type Required
path facility_external_id router lookup string; semantic ID validation requires handler/schema review true

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

Location Field Declared/inferred read type Requiredness evidence
body expected_state not declared at read site not established
body collected_state not declared at read site not established
body expected Decimal false
body collected Decimal false
body currency not declared at read site not established
body uncollected_denial_reason_code not declared at read site not established
query patient not declared at read site not established
query claim not declared at read site not established
query {computed field name} not declared at read site not established

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.

write_off · POST

Approve a reason-coded write-off. It is final once approved.

Maker-checker applies: the approver is not the author. An approved write-off is never edited in place — a correction is a compensating reversal with its own approval, which is what write-off-reversal posts.

POST /api/v1/facility/{facility_external_id}/rcm/liability/{external_id}/write-off/ — action write_off. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Location Parameter Type Required
path facility_external_id router lookup string; semantic ID validation requires handler/schema review true
path external_id router lookup string; semantic ID validation requires handler/schema review true

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

Location Field Declared/inferred read type Requiredness evidence
body approved_by reviewer reference helper default; inspect declaration
body approved_at timezone-aware datetime false
body tax_reviewed_by reviewer reference helper default; inspect declaration
body amount Decimal helper default; inspect declaration
body currency not declared at read site not established
body category not declared at read site not established
body accounting_treatment not declared at read site not established
body policy_reference not declared at read site not established
body tax_reviewed_at timezone-aware datetime false
body reason not declared at read site not established
body tax_implication not declared at read site not established
body is_waiver not declared at read site not established
query patient not declared at read site not established
query claim not declared at read site not established
query {computed field name} not declared at read site not established

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; PermissionDenied: Cannot read revenue-cycle records.

write_off_reversal · POST

Compensate an approved write-off. Never an update in place.

"An approved write-off cannot be undone by an unattended retry" — so the reversal carries its own approver, its own timestamp and its own reason, and the original row is left exactly as it was.

POST /api/v1/facility/{facility_external_id}/rcm/liability/{external_id}/write-off-reversal/ — action write_off_reversal. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Location Parameter Type Required
path facility_external_id router lookup string; semantic ID validation requires handler/schema review true
path external_id router lookup string; semantic ID validation requires handler/schema review true

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

Location Field Declared/inferred read type Requiredness evidence
body approved_by reviewer reference helper default; inspect declaration
body approved_at timezone-aware datetime false
body write_off not declared at read site not established
query patient not declared at read site not established
query claim not declared at read site not established
query {computed field name} not declared at read site not established

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: write_off must reference a write-off on this determination; 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.

Pinned source evidence

Links require access to the private source repository.