Patient billing

Learn how to manage patients' health insurance, plans, billing accounts and invoices with the Java SDK.

  • Stable unknown
  • Release candidate not available
  • Development since 0.2.0-dev.33+8af64df

ovok.patientBilling() manages patients' health insurance, plans, billing accounts and invoices, stored as FHIR Coverage, Account and Invoice. The project's PATIENT_BILLING_ENABLED setting must be on.

Add a patient's insurance

List<JsonNode> insurers = ovok.patientBilling().insurers().list(
        Map.of("country", "DE", "kind", "statutory", "query", "AOK"), RequestOptions.defaults());

JsonNode coverage = ovok.patientBilling().coverages().create("patient-id",
        Map.of("country", "DE", "kind", "statutory",
                "insurerIk", insurers.get(0).get("ik").asText(), "memberNumber", "A123456780"),
        RequestOptions.defaults());
  • kind is statutory, private or self-pay. A statutory coverage names its insurer by insurerIk and needs a valid KVNR as memberNumber; a private one takes a policy number of 1 to 30 characters.
  • An insurer outside Ovok's directory or an invalid member number throws OvokValidationException.
  • Another statutory coverage in the same period throws OvokConflictException.
  • coverages().update(coverageId, changes, ifVersion, options) changes a coverage only if it is still at the version you read. Leave out ifVersion to change it regardless.
  • coverages().remove deletes a coverage, or cancels it when a billing account names it.

Set a plan and record invoices

Setting plans and recording invoices is for project admins and admin client applications.

ovok.patientBilling().plans().set("patient-id",
        Map.of("plan", Map.of("system", "https://example.com/plans", "code", "monthly"),
                "period", Map.of("start", "2026-12-01")),
        RequestOptions.defaults());

ovok.patientBilling().invoices().record("patient-id", invoice, RequestOptions.defaults());
  • plans().set with {"plan": null} ends the plan, and answers null when there was none to end.
  • invoices().record updates the invoice recorded with the same identifier, so a retry is safe.

Read accounts and invoices

CallWhat it does
plans().retrieve(patientId, options)Reads the patient's plan, running or ended. Throws OvokNotFoundException when there is none.
accounts().list(patientId, options)Lists the patient's billing accounts.
accounts().retrieve(accountId, options)Reads one billing account.
invoices().list(patientId, params, options)Lists the patient's invoices, latest first, as a Page<JsonNode>.
invoices().retrieve(invoiceId, options)Reads one invoice.

Every method is in the PatientBillingResource reference.

See also

Last updated on

On this page