Patient billing access

Turn patient billing on for a project, and grant callers the patient_billing_* AccessPolicy rows that let patients and clinic staff read and manage insurance and invoices.

Patient billing is off until you turn it on, and then it answers only callers whose access policy grants it. Two things decide each call: a patient_billing_* capability row for the kind of action, and the Patient rows of the same policy for which patients it reaches.

Turn it on

Set PATIENT_BILLING_ENABLED to true for the project. Until then every /v1/patient-billing route answers 403 PATIENT_BILLING_DISABLED.

curl --request PUT \
  --url 'https://api.sandbox.ovok.com/v1/project/settings/PATIENT_BILLING_ENABLED' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"enabled": true}'

The capability rows

Two AccessPolicy rows are not FHIR resource types. Each names what a caller may do, and Ovok checks them by name, so a * row does not grant them and neither does a missing policy.

{ "resourceType": "patient_billing_coverages", "interaction": ["read", "create", "update", "delete"] }
RowInteractionsOpens
patient_billing_coveragesreadList the coverages
patient_billing_coveragescreateAdd a coverage
patient_billing_coveragesupdateChange a coverage
patient_billing_coveragesdeleteRemove a coverage
patient_billing_invoicesreadThe plan, the billing accounts and the invoices

A capability row takes no criteria. The Patient rows in the same policy decide which patients it reaches.

What each route needs

RouteCapability rowPatient access
Find an insurerNoneAny signed-in caller
List the coveragespatient_billing_coverages:readRead the patient
Add, change or remove a coveragepatient_billing_coverages with create, update or deleteUpdate the patient
Get the plan, list or get the billing accounts, list or get the invoicespatient_billing_invoices:readRead the patient
Set or end the plan, record an invoiceNoneProject admin or admin ClientApplication only

"Read the patient" means the caller's own policy lets them read that Patient as it is stored now. A clinic therefore sees the insurance and invoices of the patients its Patient rows cover, including those who joined after the insurance was entered.

Project admins and admin ClientApplications pass every check on every route.

Refusals

StatusTypeWhen
403PATIENT_BILLING_NOT_ALLOWEDThe policy lacks the capability row, or lets the caller read the patient but not update them on a write.
404PATIENT_BILLING_PATIENT_NOT_FOUNDThe caller cannot read the patient. Ids of patients outside their reach are not revealed.

Example policies

A patient who manages their own insurance and reads their own invoices:

{
  "resourceType": "AccessPolicy",
  "name": "Patient with insurance",
  "resource": [
    {
      "resourceType": "Patient",
      "criteria": "Patient?_id=%profile.id",
      "interaction": ["read", "update"]
    },
    {
      "resourceType": "patient_billing_coverages",
      "interaction": ["read", "create", "update", "delete"]
    },
    { "resourceType": "patient_billing_invoices", "interaction": ["read"] }
  ]
}

Clinic staff who read the insurance and invoices of their clinic's patients:

{
  "resourceType": "AccessPolicy",
  "name": "Clinic staff, billing read",
  "resource": [
    {
      "resourceType": "Patient",
      "criteria": "Patient?organization=Organization/{{CLINIC_ORGANIZATION_ID}}",
      "interaction": ["read", "search"]
    },
    { "resourceType": "patient_billing_coverages", "interaction": ["read"] },
    { "resourceType": "patient_billing_invoices", "interaction": ["read"] }
  ]
}

To let staff correct a patient's insurance as well, add update to the Patient row and create, update and delete to the coverages row.

Create and assign the policies as described in Create an AccessPolicy. The access-policy API accepts the patient_billing_ rows.

New and existing patients

Add the rows to your DEFAULT_PATIENT_ACCESS_POLICY for patients created from now on. A default does not change existing memberships, so give the rows to existing patients by updating their policy; see Defaults are not retroactive.

If you also let callers read these records through the FHIR API, give the Coverage, Account and Invoice rows readonly: true so writes go through the validated routes.

See also

Last updated on

On this page