Add a coverage
- Sandbox: available
- On your own host? Choose https://{host} in the playground.
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_coveragescreateand let you update the patient, else 403PATIENT_BILLING_NOT_ALLOWED. statutoryneedsinsurerIkand the KVNR from the health card asmemberNumber. Spaces and lower case are fine; a KVNR whose check digit fails answers 422MEMBER_NUMBER_INVALID.privateneeds the policy number asmemberNumber(1 to 30 characters), andinsurerIk, orinsurerNamefor an insurer listed without an IK.self-paytakes no insurer and no member number.- An insurer not in
GET /v1/patient-billing/insurersfor that kind answers 422INSURER_UNKNOWN. Ovok adds the insurer'sOrganizationto the project once, found by its IK, andpayorcarries its IK and name. periodholds the first and last day covered; an end before the start answers 422COVERAGE_PERIOD_INVALID. Statutory coverages may not overlap in time: 409COVERAGE_OVERLAP.orderplaces 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 }'bearerAuthorizationBearer <JWT>patientId*stringThe patient id.
^[A-Za-z0-9\-.]{1,64}$application/json- body
kind*"statutory""statutory"insurerIk*stringThe insurer's IK (Institutionskennzeichen), from GET /v1/patient-billing/insurers.
^\d{9}$memberNumber*stringStatutory: the KVNR on the health card, checked by its check digit. Private: the policy number.
1 <= length <= 40country*stringThe country whose insurance rules apply. Only DE today.
^[A-Z]{2}$period?When the coverage applies; open-ended when left out.
nullorder?integerWhich comes first when several apply: 1 is first. Last when left out.
1 <= valuenullThe coverage, added now. Location names it.
application/json- response
id*stringversion*stringSend it as If-Match: W/"<version>" to change only this version.
patientId*stringcountry*"DE""DE"kind*string"statutory""private""self-pay"status*stringactive; a removed coverage an account names is cancelled.
insurer*memberNumber*stringperiod*order*integercurl -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"}'{ "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 }' ```