# Patient billing access

Canonical page: https://docs.ovok.com/patient-billing/access

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 [#turn-it-on]

Set [`PATIENT_BILLING_ENABLED`](/settings-and-features/settings/patient-billing-enabled) to `true` for the project. Until then every `/v1/patient-billing` route answers `403` [`PATIENT_BILLING_DISABLED`](/errors/patient-billing-disabled).

```bash
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 [#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.

```json
{ "resourceType": "patient_billing_coverages", "interaction": ["read", "create", "update", "delete"] }
```

| Row | Interactions | Opens |
| --- | --- | --- |
| `patient_billing_coverages` | `read` | [List the coverages](/patient-billing/insurance#list-the-coverages) |
| `patient_billing_coverages` | `create` | [Add a coverage](/patient-billing/insurance#add-a-coverage) |
| `patient_billing_coverages` | `update` | [Change a coverage](/patient-billing/insurance#change-a-coverage) |
| `patient_billing_coverages` | `delete` | [Remove a coverage](/patient-billing/insurance#remove-a-coverage) |
| `patient_billing_invoices` | `read` | The [plan](/patient-billing/plans-and-invoices#get-the-plan), the [billing accounts](/patient-billing/plans-and-invoices#read-the-billing-account) and the [invoices](/patient-billing/plans-and-invoices#list-the-invoices) |

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

## What each route needs [#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 [#refusals]

| Status | Type | When |
| --- | --- | --- |
| [`403`](/errors/forbidden) | [`PATIENT_BILLING_NOT_ALLOWED`](/errors/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`](/errors/not-found) | [`PATIENT_BILLING_PATIENT_NOT_FOUND`](/errors/patient-billing-patient-not-found) | The caller cannot read the patient. Ids of patients outside their reach are not revealed. |

## Example policies [#example-policies]

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

```json
{
  "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:

```json
{
  "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](/access-policies/create-access-policy). The access-policy API accepts the `patient_billing_` rows.

## New and existing patients [#new-and-existing-patients]

Add the rows to your [`DEFAULT_PATIENT_ACCESS_POLICY`](/settings-and-features/settings/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](/access-policies/defaults#defaults-are-project-local-and-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 [#see-also]

- [Patient billing and insurance](/patient-billing)
- [AccessPolicy model and membership](/access-policies/policy-model)
- [Signals route policies](/access-policies/signals), which use the same kind of capability row
