Insurance
Add, change and remove a patient's health insurance as FHIR Coverage, with the insurer directory, the kinds, the member-number check and the coverage order.
A patient's insurance is a list of coverages, each naming an insurer and a member number, in the order they apply. Add one with POST, change it with PATCH, and read the list with GET. Ovok validates each write before it stores a FHIR Coverage.
Who may call each route depends on the caller's access policy; see Access. The examples use PATIENT_ID for the patient's id and OVOK_TOKEN for the caller's token.
Kinds
Every coverage has a kind, which decides what it needs and how Ovok codes it with the German base profile http://fhir.de/CodeSystem/versicherungsart-de-basis.
kind | FHIR code | Insurer | memberNumber | Rules |
|---|---|---|---|---|
statutory | GKV | Required: insurerIk of a statutory fund | The KVNR, checked by its check digit | Statutory coverages may not overlap in time. |
private | PKV | Required: insurerIk, or insurerName for an insurer listed without an IK | The policy number, 1 to 30 characters | May overlap other coverages. For a statutory patient's supplementary insurance, add a private coverage with order 2. |
self-pay | SEL | None | None | Takes no insurer and no member number. |
Find an insurer
Lists the insurers a coverage may name, so you can build an insurer picker. Any signed-in caller can use it, in a project with PATIENT_BILLING_ENABLED on.
curl --get 'https://api.sandbox.ovok.com/v1/patient-billing/insurers' \
--data-urlencode 'country=DE' \
--data-urlencode 'kind=statutory' \
--data-urlencode 'query=tk' \
--header "Authorization: Bearer ${OVOK_TOKEN}"| Query parameter | Required | Description |
|---|---|---|
country | No | DE, the default and the only supported country. |
kind | No | statutory or private. Leave it out for both. |
query | No | Part of the name in any case, or the start of the IK. |
{
"items": [
{
"country": "DE",
"ik": "101575519",
"name": "Techniker Krankenkasse",
"kind": "statutory"
}
]
}A statutory fund always has an ik. A private insurer has one only where it has an IK, otherwise ik is null and you name the insurer by name.
Ovok maintains the directory and updates it with the platform. It does not list every insurer yet: one that is missing answers 422 INSURER_UNKNOWN when you add a coverage for it.
Add a coverage
Adds an insurance to a patient and answers 201 with Location: /v1/patient-billing/coverages/<id>.
curl --request POST \
--url "https://api.sandbox.ovok.com/v1/patient-billing/patients/${PATIENT_ID}/coverages" \
--header "Authorization: Bearer ${OVOK_TOKEN}" \
--header 'Content-Type: application/json' \
--data '{
"country": "DE",
"kind": "statutory",
"insurerIk": "101575519",
"memberNumber": "a123 456 780",
"period": { "start": "2025-01-01", "end": null },
"order": 1
}'| Body field | Required | Description |
|---|---|---|
country | Yes | DE. |
kind | Yes | statutory, private or self-pay. |
insurerIk | By kind | The insurer's 9-digit IK from the directory. |
insurerName | Private only | An insurer listed without an IK, by its directory name in any case. |
memberNumber | By kind | The KVNR or the policy number. Not allowed for self-pay. |
period | No | start and end, each a date (2025-01-01) or null. Without a period the coverage is open-ended. |
order | No | A whole number from 1, where 1 comes first. The coverage comes last when you leave it out. |
Fields not listed here are refused. Ovok adds the insurer's Organization to the project once, found by its IK, and the coverage's payor carries its IK and name.
{
"id": "7b19d0aa-3f4c-4c2e-9d11-5c0e8f0a2b61",
"version": "1",
"patientId": "5f2c9a1e-8d3b-4a7e-b6c4-2e9f1d0a7c38",
"country": "DE",
"kind": "statutory",
"status": "active",
"insurer": { "ik": "101575519", "name": "Techniker Krankenkasse" },
"memberNumber": "A123456780",
"period": { "start": "2025-01-01", "end": null },
"order": 1
}| Response field | Meaning |
|---|---|
id, patientId | The coverage and the patient it belongs to. |
version | The coverage's version. Send it as If-Match to change only this version. |
status | active. |
insurer | The insurer's ik and name. null for self-pay. |
memberNumber | As stored: a KVNR is upper case without spaces. null for self-pay. |
period | start and end, or null when none was given. |
order | Where the coverage stands among the patient's others. |
Errors
| Status | Type | When |
|---|---|---|
409 | COVERAGE_OVERLAP | Another statutory coverage runs in that period. coverageId in the answer names it. |
409 | conflict | Another change to the patient's coverages is still running. Send yours again. |
422 | MEMBER_NUMBER_INVALID | The KVNR fails its check digit, or the policy number is empty or longer than 30 characters. |
422 | INSURER_UNKNOWN | No insurer of that kind has the IK or name. |
422 | COVERAGE_PERIOD_INVALID | The period ends before it starts. |
422 | COUNTRY_UNSUPPORTED | country is not DE. |
List the coverages
Returns the patient's active coverages, in the order they apply. The app plan is never among them.
curl --get "https://api.sandbox.ovok.com/v1/patient-billing/patients/${PATIENT_ID}/coverages" \
--header "Authorization: Bearer ${OVOK_TOKEN}"The answer is { "items": [ ... ] }, each item shaped as above.
Change a coverage
Changes a coverage's insurer, member number, period or order. Fields you leave out stay as they are. The whole coverage is checked again with the rules and errors of adding one.
curl --request PATCH \
--url "https://api.sandbox.ovok.com/v1/patient-billing/coverages/${COVERAGE_ID}" \
--header "Authorization: Bearer ${OVOK_TOKEN}" \
--header 'If-Match: W/"1"' \
--header 'Content-Type: application/json' \
--data '{ "order": 2 }'| Body field | Description |
|---|---|
insurerIk, insurerName | Another insurer of the same kind. |
memberNumber | A new KVNR or policy number. |
period | New dates. null makes the coverage open-ended. |
order | The new place in the list. |
A coverage's kind never changes. Remove it and add another instead.
If-Match is optional. With it, the change lands only on the version it names; otherwise the route answers 412 COVERAGE_VERSION_MISMATCH. A value that is not an entity tag such as W/"1" answers 400.
An unknown or removed coverage, or one the caller cannot see, answers 404 COVERAGE_NOT_FOUND.
Remove a coverage
Removes a coverage and answers 204. The coverage no longer appears in the list.
curl --request DELETE \
--url "https://api.sandbox.ovok.com/v1/patient-billing/coverages/${COVERAGE_ID}" \
--header "Authorization: Bearer ${OVOK_TOKEN}"A coverage that no billing account names is deleted. One that an account names is cancelled instead, with its period ending today, so billing history stays whole.
Coverage order
order runs from 1 over the patient's active coverages. Adding, moving or removing a coverage renumbers the others in the same transaction, so the numbers never skip or repeat. Changes to one patient's coverages run one at a time.
The KVNR check
A KVNR (Krankenversichertennummer) is one letter followed by nine digits. The last digit checks the rest:
- Replace the letter with its position as two digits:
Ais01,Zis26. - Take those two digits and the next eight digits of the number: ten digits in all. Weight them 1, 2, 1, 2 and so on, and add the digits of each product.
- The last digit of the total must equal the KVNR's last digit.
A123456780 passes. Ovok removes spaces and upper-cases the number before it checks it, and answers 422 MEMBER_NUMBER_INVALID when it fails.
What Ovok stores
Each coverage is a FHIR Coverage in the patient's compartment. Read it through the FHIR API when you need a field these routes leave out.
{
"resourceType": "Coverage",
"status": "active",
"type": {
"coding": [{
"system": "http://fhir.de/CodeSystem/versicherungsart-de-basis",
"code": "GKV",
"display": "gesetzliche Krankenversicherung"
}]
},
"subscriberId": "A123456780",
"beneficiary": { "reference": "Patient/5f2c9a1e-8d3b-4a7e-b6c4-2e9f1d0a7c38" },
"relationship": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
"code": "self"
}]
},
"period": { "start": "2025-01-01" },
"payor": [{
"reference": "Organization/9d41b7c0-6e2a-4f3d-8b15-a0c7e4d2f193",
"identifier": {
"system": "http://fhir.de/sid/arge-ik/iknr",
"value": "101575519"
},
"display": "Techniker Krankenkasse"
}],
"order": 1
}A self-pay coverage has the code SEL and names the patient as its payor. Write insurance through these routes rather than through /fhir, so every coverage passes the checks above.
See also
Last updated on
Patient billing and insurance
Store a patient's health insurance, the plan they pay your app for, their billing account and their invoices as FHIR resources, starting with Germany.
Plans and invoices
Record the plan a patient pays your app for and each payment from your server's webhooks, and read the patient's plan, billing account and invoices.