# Insurance

Canonical page: https://docs.ovok.com/patient-billing/insurance

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](/patient-billing/access). The examples use `PATIENT_ID` for the patient's id and `OVOK_TOKEN` for the caller's token.

## Kinds [#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](#the-kvnr-check) | 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 [#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`](/settings-and-features/settings/patient-billing-enabled) on.

```bash
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. |

```json
{
  "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`](/errors/insurer-unknown) when you add a coverage for it.

## Add a coverage [#add-a-coverage]

Adds an insurance to a patient and answers `201` with `Location: /v1/patient-billing/coverages/<id>`.

```bash
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](#find-an-insurer). |
| `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.

```json
{
  "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](#change-a-coverage) 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 [#errors]

| Status | Type | When |
| --- | --- | --- |
| [`409`](/errors/conflict) | [`COVERAGE_OVERLAP`](/errors/coverage-overlap) | Another statutory coverage runs in that period. `coverageId` in the answer names it. |
| [`409`](/errors/conflict) | [`conflict`](/errors/conflict) | Another change to the patient's coverages is still running. Send yours again. |
| [`422`](/errors/validation-failed) | [`MEMBER_NUMBER_INVALID`](/errors/member-number-invalid) | The KVNR fails its check digit, or the policy number is empty or longer than 30 characters. |
| [`422`](/errors/validation-failed) | [`INSURER_UNKNOWN`](/errors/insurer-unknown) | No insurer of that kind has the IK or name. |
| [`422`](/errors/validation-failed) | [`COVERAGE_PERIOD_INVALID`](/errors/coverage-period-invalid) | The period ends before it starts. |
| [`422`](/errors/validation-failed) | [`COUNTRY_UNSUPPORTED`](/errors/country-unsupported) | `country` is not `DE`. |

## List the coverages [#list-the-coverages]

Returns the patient's active coverages, in the order they apply. The app plan is never among them.

```bash
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 [#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](#errors).

```bash
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`](/errors/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`](/errors/coverage-not-found).

## Remove a coverage [#remove-a-coverage]

Removes a coverage and answers `204`. The coverage no longer appears in the list.

```bash
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 [#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 [#the-kvnr-check]

A KVNR (Krankenversichertennummer) is one letter followed by nine digits. The last digit checks the rest:

1. Replace the letter with its position as two digits: `A` is `01`, `Z` is `26`.
2. 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.
3. 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`](/errors/member-number-invalid) when it fails.

## What Ovok stores [#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.

```json
{
  "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 [#see-also]

- [Patient billing and insurance](/patient-billing)
- [Plans, accounts and invoices](/patient-billing/plans-and-invoices)
- [Access](/patient-billing/access)
