Patient billing and insurance
Store a patient's health insurance, the plan they pay your app for, their billing account and their invoices as FHIR resources, starting with Germany.
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.
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 and Plans, accounts and invoices.
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 | API |
| List the coverages | GET | /v1/patient-billing/patients/:patientId/coverages | Insurance | API |
| Add a coverage | POST | /v1/patient-billing/patients/:patientId/coverages | Insurance | API |
| Change a coverage | PATCH | /v1/patient-billing/coverages/:coverageId | Insurance | API |
| Remove a coverage | DELETE | /v1/patient-billing/coverages/:coverageId | Insurance | API |
| Get the plan | GET | /v1/patient-billing/patients/:patientId/plan | Plans and invoices | API |
| Set or end the plan | PUT | /v1/patient-billing/patients/:patientId/plan | Plans and invoices | API |
| List the billing accounts | GET | /v1/patient-billing/patients/:patientId/accounts | Plans and invoices | API |
| Get a billing account | GET | /v1/patient-billing/accounts/:accountId | Plans and invoices | API |
| Record an invoice | POST | /v1/patient-billing/patients/:patientId/invoices | Plans and invoices | API |
| List the invoices | GET | /v1/patient-billing/patients/:patientId/invoices | Plans and invoices | API |
| Get an invoice | GET | /v1/patient-billing/invoices/:invoiceId | Plans and invoices | API |
Germany first
Insurance rules are per country, and DE is the only country supported. Any other country answers 422 COUNTRY_UNSUPPORTED. German insurance is coded with the German FHIR base profiles, and insurers are identified by their IK (Institutionskennzeichen).
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
- Turn on
PATIENT_BILLING_ENABLED. It is off by default, and every route answers403PATIENT_BILLING_DISABLEDuntil it is on. - Add the
patient_billing_*rows to the access policies of the callers who need them. Turning the setting on grants nobody access. See Access. - Write plans and invoices from your server, with a project admin's or an admin ClientApplication's token. No policy row lets anyone else write them.
Errors every route can answer
| Status | Type | When |
|---|---|---|
401 | unauthenticated | The bearer token is missing or invalid. |
403 | PATIENT_BILLING_DISABLED | The project's switch is off. |
403 | PATIENT_BILLING_NOT_ALLOWED | The access policy lacks the capability row or the Patient access the route needs. |
404 | 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
- Insurance: coverages, their kinds, the insurer directory and the member-number rules.
- Plans, accounts and invoices: record a patient's plan and payments from a server webhook.
- Access: the project switch, the capability rows and example policies.
Last updated on