# Patient billing and insurance

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

Ovok's patient billing API stores who pays for a patient's care and what the patient pays your app: their health insurance, their app plan, their billing account and their invoices. Each is a standard FHIR R4 resource (`Coverage`, `Account` or `Invoice`), reached through validated routes under `/v1/patient-billing`.

The API checks what FHIR cannot: a statutory member number's check digit, a listed insurer, and two statutory coverages that run at the same time. Everything it writes stays readable through the FHIR API.

```mermaid
flowchart LR
  patient[Patient app] -->|Add and change insurance| api["/v1/patient-billing"]
  clinic[Clinic staff] -->|Read insurance and invoices| api
  server[Your server] -->|Set the plan, record invoices| api
  api --> coverage[FHIR Coverage]
  api --> account[FHIR Account]
  api --> invoice[FHIR Invoice]
```

## Insurance and the app plan [#insurance-and-the-app-plan]

A patient has two kinds of `Coverage`, and the routes keep them apart. Coverage routes never return the app plan, and the plan route never returns insurance.

| | Insurance | App plan |
| --- | --- | --- |
| Says | Who pays for the patient's care | Which plan the patient pays your app for |
| Written by | The patient, a profile holder or clinic staff, as their access policy allows | Your server, from your payment or store webhooks |
| Kinds | Statutory, private or self-pay | One plan per patient, in your own code system |
| Routes | `/patients/:patientId/coverages` and `/coverages/:coverageId` | `/patients/:patientId/plan` |
| Read with | `patient_billing_coverages:read` | `patient_billing_invoices:read` |

Invoices record each paid period of the plan, and the patient's billing account ties the plan and the invoices together. See [Insurance](/patient-billing/insurance) and [Plans, accounts and invoices](/patient-billing/plans-and-invoices).

## Routes [#routes]

All routes sit under `/v1/patient-billing` and need a bearer token. The project comes from the token.

| Operation | Method | Path | Details | Reference |
| --- | --- | --- | --- | --- |
| Find an insurer | `GET` | `/v1/patient-billing/insurers` | [Insurance](/patient-billing/insurance#find-an-insurer) | [API](/api/patient-billing/list-health-insurers) |
| List the coverages | `GET` | `/v1/patient-billing/patients/:patientId/coverages` | [Insurance](/patient-billing/insurance#list-the-coverages) | [API](/api/patient-billing/list-a-patient-s-coverages) |
| Add a coverage | `POST` | `/v1/patient-billing/patients/:patientId/coverages` | [Insurance](/patient-billing/insurance#add-a-coverage) | [API](/api/patient-billing/add-a-coverage) |
| Change a coverage | `PATCH` | `/v1/patient-billing/coverages/:coverageId` | [Insurance](/patient-billing/insurance#change-a-coverage) | [API](/api/patient-billing/change-a-coverage) |
| Remove a coverage | `DELETE` | `/v1/patient-billing/coverages/:coverageId` | [Insurance](/patient-billing/insurance#remove-a-coverage) | [API](/api/patient-billing/remove-a-coverage) |
| Get the plan | `GET` | `/v1/patient-billing/patients/:patientId/plan` | [Plans and invoices](/patient-billing/plans-and-invoices#get-the-plan) | [API](/api/patient-billing/get-a-patient-s-plan) |
| Set or end the plan | `PUT` | `/v1/patient-billing/patients/:patientId/plan` | [Plans and invoices](/patient-billing/plans-and-invoices#set-or-end-the-plan) | [API](/api/patient-billing/set-a-patient-s-plan) |
| List the billing accounts | `GET` | `/v1/patient-billing/patients/:patientId/accounts` | [Plans and invoices](/patient-billing/plans-and-invoices#read-the-billing-account) | [API](/api/patient-billing/list-a-patient-s-billing-accounts) |
| Get a billing account | `GET` | `/v1/patient-billing/accounts/:accountId` | [Plans and invoices](/patient-billing/plans-and-invoices#read-the-billing-account) | [API](/api/patient-billing/get-a-billing-account) |
| Record an invoice | `POST` | `/v1/patient-billing/patients/:patientId/invoices` | [Plans and invoices](/patient-billing/plans-and-invoices#record-an-invoice) | [API](/api/patient-billing/record-an-invoice) |
| List the invoices | `GET` | `/v1/patient-billing/patients/:patientId/invoices` | [Plans and invoices](/patient-billing/plans-and-invoices#list-the-invoices) | [API](/api/patient-billing/list-a-patient-s-invoices) |
| Get an invoice | `GET` | `/v1/patient-billing/invoices/:invoiceId` | [Plans and invoices](/patient-billing/plans-and-invoices#get-an-invoice) | [API](/api/patient-billing/get-an-invoice) |

## Germany first [#germany-first]

Insurance rules are per country, and `DE` is the only country supported. Any other `country` answers `422` [`COUNTRY_UNSUPPORTED`](/errors/country-unsupported). German insurance is coded with the German FHIR base profiles, and insurers are identified by their IK (Institutionskennzeichen).

## What is not included [#what-is-not-included]

Sending claims to insurers is not part of this API. It is on the roadmap. Checking that cover is in force and recording insurers' payments are not included either.

## Before you integrate [#before-you-integrate]

1. Turn on [`PATIENT_BILLING_ENABLED`](/settings-and-features/settings/patient-billing-enabled). It is off by default, and every route answers `403` [`PATIENT_BILLING_DISABLED`](/errors/patient-billing-disabled) until it is on.
2. Add the `patient_billing_*` rows to the access policies of the callers who need them. Turning the setting on grants nobody access. See [Access](/patient-billing/access).
3. Write plans and invoices from your server, with a project admin's or an admin [ClientApplication's](/applications#admin) token. No policy row lets anyone else write them.

## Errors every route can answer [#errors-every-route-can-answer]

| Status | Type | When |
| --- | --- | --- |
| [`401`](/errors/unauthenticated) | [`unauthenticated`](/errors/unauthenticated) | The bearer token is missing or invalid. |
| [`403`](/errors/forbidden) | [`PATIENT_BILLING_DISABLED`](/errors/patient-billing-disabled) | The project's switch is off. |
| [`403`](/errors/forbidden) | [`PATIENT_BILLING_NOT_ALLOWED`](/errors/patient-billing-not-allowed) | The access policy lacks the capability row or the Patient access the route needs. |
| [`404`](/errors/not-found) | [`PATIENT_BILLING_PATIENT_NOT_FOUND`](/errors/patient-billing-patient-not-found) | The caller can see no patient with that id. |

Each page lists the errors specific to its routes.

## Pages in this section [#pages-in-this-section]

- [Insurance](/patient-billing/insurance): coverages, their kinds, the insurer directory and the member-number rules.
- [Plans, accounts and invoices](/patient-billing/plans-and-invoices): record a patient's plan and payments from a server webhook.
- [Access](/patient-billing/access): the project switch, the capability rows and example policies.
