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"] }| Row | Interactions | Opens |
|---|---|---|
patient_billing_coverages | read | List the coverages |
patient_billing_coverages | create | Add a coverage |
patient_billing_coverages | update | Change a coverage |
patient_billing_coverages | delete | Remove a coverage |
patient_billing_invoices | read | The 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
| Route | Capability row | Patient access |
|---|---|---|
| Find an insurer | None | Any signed-in caller |
| List the coverages | patient_billing_coverages:read | Read the patient |
| Add, change or remove a coverage | patient_billing_coverages with create, update or delete | Update the patient |
| Get the plan, list or get the billing accounts, list or get the invoices | patient_billing_invoices:read | Read the patient |
| Set or end the plan, record an invoice | None | Project 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
| Status | Type | When |
|---|---|---|
403 | PATIENT_BILLING_NOT_ALLOWED | The policy lacks the capability row, or lets the caller read the patient but not update them on a write. |
404 | PATIENT_BILLING_PATIENT_NOT_FOUND | The 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
- Patient billing and insurance
- AccessPolicy model and membership
- Signals route policies, which use the same kind of capability row
Last updated on