Patient billing

Change a coverage

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

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

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

Authorization

bearer
headerAuthorizationBearer <JWT>

Path Parameters

coverageId*string

The coverage id.

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

Request Body

application/json
  1. body
insurerIk?string

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

Match^\d{9}$
insurerName?string

A private insurer without an IK, by its name in GET /v1/patient-billing/insurers.

Length1 <= length <= 200
memberNumber?string

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

Length1 <= length <= 40
period?

null makes the coverage open-ended.

order?integer

Which comes first when several apply: 1 is first.

Range1 <= value

Response Body

The coverage as changed.

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 PATCH 'https://api.sandbox.ovok.com/v1/patient-billing/coverages/string' \  -H 'Content-Type: application/json' \  -d '{}'
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}

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

Remove a coverage DELETE

Removes a coverage from the patient's insurance. The others are renumbered in the same transaction. **Scope:** the caller's project, with `PATIENT_BILLING_ENABLED` on. ## Behaviour - Your access policy must grant `patient_billing_coverages` `delete` and let you update the coverage's patient, else **403** `PATIENT_BILLING_NOT_ALLOWED`. - A coverage no billing account names is deleted. One an account names is cancelled instead, its period ending today, so billing history stays whole. - Changes to one patient's coverages run one at a time: another still running answers **409**; send yours again. - Answers **204** either way; the coverage no longer appears in the patient's list. ## Example ```bash curl -X DELETE 'https://api.sandbox.ovok.com/v1/patient-billing/coverages/<coverageId>' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```