Patient billing

Add a coverage

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

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

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 }'

Authorization

bearer
headerAuthorizationBearer <JWT>

Path Parameters

patientId*string

The patient id.

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

Request Body

application/json
  1. body
kind*"statutory"
Value in"statutory"
insurerIk*string

The insurer's IK (Institutionskennzeichen), from GET /v1/patient-billing/insurers.

Match^\d{9}$
memberNumber*string

Statutory: the KVNR on the health card, checked by its check digit. Private: the policy number.

Length1 <= length <= 40
country*string

The country whose insurance rules apply. Only DE today.

Match^[A-Z]{2}$
period?

When the coverage applies; open-ended when left out.

Defaultnull
order?integer

Which comes first when several apply: 1 is first. Last when left out.

Range1 <= value
Defaultnull

Response Body

The coverage, added now. Location names it.

application/json
  1. response
id*string
version*string

Send it as If-Match: W/"<version>" to change only this version.

patientId*string
country*"DE"
Value in"DE"
kind*string
Value in"statutory""private""self-pay"
status*string

active; a removed coverage an account names is cancelled.

insurer*
memberNumber*string
period*
order*integer
Example Request
curl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/patients/string/coverages' \  -H 'Content-Type: application/json' \  -d '{  "kind": "statutory",  "insurerIk": "string",  "memberNumber": "string",  "country": "string"}'
Example Response
{  "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 a patient's coverages GET

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 ```bash curl 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/coverages' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```

Change a coverage PATCH

Changes a coverage's insurer, member number, period or order. Fields left out stay as they are; its kind never changes, so remove it and add another instead. **Scope:** the caller's project, with `PATIENT_BILLING_ENABLED` on. ## Behaviour - Your access policy must grant `patient_billing_coverages` `update` and let you update the coverage's patient, else **403** `PATIENT_BILLING_NOT_ALLOWED`. A coverage you cannot see answers **404** `COVERAGE_NOT_FOUND`. - The coverage is checked again as a whole, with the same rules and errors as adding one. - `period: null` makes the coverage open-ended. `order` moves it; 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. - `If-Match: W/"<version>"` is optional. With it, the change lands only on that version, else **412** `COVERAGE_VERSION_MISMATCH`. ## Example ```bash curl -X PATCH 'https://api.sandbox.ovok.com/v1/patient-billing/coverages/<coverageId>' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'If-Match: W/"2"' \ -H 'Content-Type: application/json' \ -d '{ "order": 1 }' ```