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.

InsuranceApp plan
SaysWho pays for the patient's careWhich plan the patient pays your app for
Written byThe patient, a profile holder or clinic staff, as their access policy allowsYour server, from your payment or store webhooks
KindsStatutory, private or self-payOne plan per patient, in your own code system
Routes/patients/:patientId/coverages and /coverages/:coverageId/patients/:patientId/plan
Read withpatient_billing_coverages:readpatient_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.

OperationMethodPathDetailsReference
Find an insurerGET/v1/patient-billing/insurersInsuranceAPI
List the coveragesGET/v1/patient-billing/patients/:patientId/coveragesInsuranceAPI
Add a coveragePOST/v1/patient-billing/patients/:patientId/coveragesInsuranceAPI
Change a coveragePATCH/v1/patient-billing/coverages/:coverageIdInsuranceAPI
Remove a coverageDELETE/v1/patient-billing/coverages/:coverageIdInsuranceAPI
Get the planGET/v1/patient-billing/patients/:patientId/planPlans and invoicesAPI
Set or end the planPUT/v1/patient-billing/patients/:patientId/planPlans and invoicesAPI
List the billing accountsGET/v1/patient-billing/patients/:patientId/accountsPlans and invoicesAPI
Get a billing accountGET/v1/patient-billing/accounts/:accountIdPlans and invoicesAPI
Record an invoicePOST/v1/patient-billing/patients/:patientId/invoicesPlans and invoicesAPI
List the invoicesGET/v1/patient-billing/patients/:patientId/invoicesPlans and invoicesAPI
Get an invoiceGET/v1/patient-billing/invoices/:invoiceIdPlans and invoicesAPI

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

  1. Turn on PATIENT_BILLING_ENABLED. It is off by default, and every route answers 403 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.
  3. 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

StatusTypeWhen
401unauthenticatedThe bearer token is missing or invalid.
403PATIENT_BILLING_DISABLEDThe project's switch is off.
403PATIENT_BILLING_NOT_ALLOWEDThe access policy lacks the capability row or the Patient access the route needs.
404PATIENT_BILLING_PATIENT_NOT_FOUNDThe 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

On this page