Patient billing

List a patient's coverages

  • Sandbox: available
  • On your own host? Choose https://{host} in the playground.
GET
/v1/patient-billing/patients/{patientId}/coverages

Lists a patient's health insurance: their active coverages, in the order they apply, first first. Each is a FHIR Coverage in the patient's compartment. The app plan from /plan is never among them.

Scope: the caller's project, with PATIENT_BILLING_ENABLED on.

Behaviour

  • Your access policy must grant patient_billing_coverages read and let you read the patient as stored now, so a clinic sees the insurance of the patients enrolled with it. Without the row: 403 PATIENT_BILLING_NOT_ALLOWED. A patient you cannot read: 404 PATIENT_BILLING_PATIENT_NOT_FOUND.
  • Project admins and admin ClientApplications may read every patient's.

Example

curl 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/coverages' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'

Authorization

bearer
headerAuthorizationBearer <JWT>

Path Parameters

patientId*string

The patient id.

Match^[A-Za-z0-9\-.]{1,64}$

Response Body

The patient's active insurance coverages, in the order they apply.

application/json
  1. response
items*array<>
Example Request
curl -X GET 'https://api.sandbox.ovok.com/v1/patient-billing/patients/string/coverages'
Example Response
{  "items": [    {      "id": "string",      "version": "string",      "patientId": "string",      "country": "DE",      "kind": "statutory",      "status": "string",      "insurer": {        "ik": "string",        "name": "string"      },      "memberNumber": "string",      "period": {        "start": "string",        "end": "string"      },      "order": 0    }  ]}

List health insurers GET

Lists the health insurers a coverage may name: German statutory funds (gesetzliche Krankenkassen) with their IK, and private insurers, with their IK where they have one. Use it to build an insurer picker. **Scope:** any signed-in caller, in a project with `PATIENT_BILLING_ENABLED` on. ## Behaviour - `country` is `DE`, the only one supported; any other answers **422** `COUNTRY_UNSUPPORTED`. - `kind` keeps only `statutory` or only `private` insurers. - `query` matches part of the name, in any case, or the start of the IK. - The list is Ovok's insurer directory, refreshed in ovok-core releases. ## Example ```bash curl 'https://api.sandbox.ovok.com/v1/patient-billing/insurers?country=DE&kind=statutory&query=tk' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```

Add a coverage POST

Adds a health insurance to a patient: statutory (`GKV`), private (`PKV`) or self-pay (`SEL`), coded as in the German base profiles (`http://fhir.de/CodeSystem/versicherungsart-de-basis`). **Scope:** the caller's project, with `PATIENT_BILLING_ENABLED` on. ## Behaviour - Your access policy must grant `patient_billing_coverages` `create` and let you update the patient, else **403** `PATIENT_BILLING_NOT_ALLOWED`. - `statutory` needs `insurerIk` and the KVNR from the health card as `memberNumber`. Spaces and lower case are fine; a KVNR whose check digit fails answers **422** `MEMBER_NUMBER_INVALID`. - `private` needs the policy number as `memberNumber` (1 to 30 characters), and `insurerIk`, or `insurerName` for an insurer listed without an IK. - `self-pay` takes no insurer and no member number. - An insurer not in `GET /v1/patient-billing/insurers` for that kind answers **422** `INSURER_UNKNOWN`. Ovok adds the insurer's `Organization` to the project once, found by its IK, and `payor` carries its IK and name. - `period` holds the first and last day covered; an end before the start answers **422** `COVERAGE_PERIOD_INVALID`. Statutory coverages may not overlap in time: **409** `COVERAGE_OVERLAP`. - `order` places the coverage among the patient's others (1 is first); left out, it comes last. The others are renumbered in the same transaction. - Changes to one patient's coverages run one at a time: another still running answers **409**; send yours again. - Answers **201** with `Location: /v1/patient-billing/coverages/<id>`. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/coverages' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "country": "DE", "kind": "statutory", "insurerIk": "101575519", "memberNumber": "A123456780", "period": { "start": "2025-01-01", "end": null }, "order": 1 }' ```