Effective dates, validity and future values

You query table datasets for an effective date. The response contains the value that applies on that day. Without one, the current day in Germany applies. Datasets whose values always apply for a whole calendar year take a year instead of a date.

An example: on December 31, 2026, the minimum wage is €13.9 per hour; on January 1, 2027 it is €14.6. Two requests, one day apart:

curl "https://api.quellenkontor.dev/v1/hr/mindestlohn?datum=2026-12-31" \
  -H "Authorization: Bearer $QK_KEY"

curl "https://api.quellenkontor.dev/v1/hr/mindestlohn?datum=2027-01-01" \
  -H "Authorization: Bearer $QK_KEY"

Calculators take their own inputs, for example the start of employment (Eintritt) and the date notice is received (Zugang). Which ones apply is listed in the reference for each dataset.

Every response from a table dataset states since when and until when the value applies, and what it is based on:

With naechster_wert you can spot an adopted change today and prepare your software for it.

We add future values as soon as they are officially promulgated, meaning they appear in the Federal Law Gazette (Bundesgesetzblatt) or the Federal Gazette (Bundesanzeiger). We do not add draft bills or cabinet decisions. Until promulgation, the API explicitly says that a value is missing. It never guesses.

Value not set yet

For years without a promulgated value, the API responds with status 404 and the code kein_wert. The contribution ceilings (Rechengrößen) are currently available up to 2026. A request for 2027 gives:

{
  "fehler": {
    "code": "kein_wert",
    "nachricht": "Die Rechengrößen für 2027 sind noch nicht amtlich festgelegt. Verfügbar bis 2026.",
    "parameter": "jahr"
  }
}

Partly set

For the contribution rates (Beitragssätze), all components are promulgated through December 31, 2026. For later effective dates, the API returns the most recently adopted rates and sets vorlaeufig to true. Request for June 1, 2027:

{
  "vorlaeufig": true,
  "hinweise": [
    "Für Stichtage nach dem 31.12.2026 sind noch nicht alle Sätze festgelegt. Angezeigt sind die zuletzt beschlossenen Werte. Fehlende Bestandteile, etwa der durchschnittliche Zusatzbeitrag, folgen nach ihrer Bekanntmachung."
  ]
}

Announced, but no value yet

Sometimes it is already certain that a value will change, but not yet by how much. Example: from January 1, 2027, the flat-rate health insurance contribution for a commercial mini-job (gewerblicher Minijob) follows the average additional contribution rate, which is not published until autumn. Until then, the component appears in the response with wert: null, status: "ausstehend" (pending) and the legal basis of the new rule, instead of silently being missing:

{
  "id": "gewerblich_kv",
  "name": "Pauschalbeitrag Krankenversicherung, gewerblicher Minijob",
  "gruppe": "Gewerblich",
  "einheit": "prozent",
  "wert": null,
  "gueltig_ab": "2027-01-01",
  "gueltig_bis": null,
  "rechtsgrundlage": "§ 249b Satz 1 SGB V in der Fassung von Artikel 1 Nr. 64 des GKV-Beitragssatzstabilisierungsgesetzes, in Kraft ab 01.01.2027",
  "quelle": {
    "titel": "Gesetz zur Stabilisierung der Beitragssätze in der gesetzlichen Krankenversicherung vom 24. Juli 2026 (BGBl. 2026 I Nr. 228)",
    "url": "https://www.recht.bund.de/bgbl/1/2026/228/VO.html"
  },
  "hinweis": "Nur für gesetzlich krankenversicherte Minijobber. Ab 01.01.2027 gilt der allgemeine Beitragssatz zuzüglich des durchschnittlichen Zusatzbeitragssatzes (§ 249b Satz 1 SGB V in der ab 2027 geltenden Fassung). Den Wert tragen wir im wöchentlichen Prüflauf ein, nachdem der durchschnittliche Zusatzbeitragssatz für 2027 bekannt gemacht ist.",
  "naechster_wert": null,
  "status": "ausstehend",
  "erwartet": "allgemeiner Beitragssatz plus durchschnittlicher Zusatzbeitragssatz 2027, dessen Bekanntmachung bis 01.11.2026 erwartet wird"
}

Values set yearly

Some values apply only for one calendar year, for example the rate of the artists' social security levy (Künstlersozialabgabe). For years after the most recent ordinance, the API responds with kein_wert, even though the old rate will probably continue to apply.

Before 2015

The tables go back to January 1, 2015, and the apprentice minimum pay (Mindestausbildungsvergütung) back to a training start of January 1, 2020. Earlier effective dates also result in kein_wert.

Every table has a history with all steps since 2015. Querying the history counts as one normal request. It is useful for importing the values into your own database once, in full. Every row has an end date in gueltig_bis; only the currently applicable step has null.

curl "https://api.quellenkontor.dev/v1/hr/mindestlohn/verlauf" \
  -H "Authorization: Bearer $QK_KEY"

With von and bis you only get the steps that apply within that period; for datasets built from components, adding bestandteil returns just one entry:

curl "https://api.quellenkontor.dev/v1/hr/pflegemindestlohn/verlauf?bestandteil=pflegefachkraft&von=2025-01-01" \
  -H "Authorization: Bearer $QK_KEY"

With format=csv you get the same history as a CSV file, see Responses and CSV.

All dates are calendar days without a time, in the format YYYY-MM-DD. "Today" means the current day in Germany (Europe/Berlin). A new value applies from 00:00 German time on its effective date. If your server runs in a different time zone, pass the date explicitly instead of relying on "today".

The calculators apply the statutory rule mechanically: notice periods under § 622 BGB, vacation under the Federal Vacation Act (Bundesurlaubsgesetz), maternity protection periods under § 3 MuSchG, public holidays under each state's public holiday act. They do not know about employment or collective agreements, or the specifics of an individual case. Where a calculation makes an assumption, it appears in the hinweise field.

The reference for each calculator describes which rule it applies and which cases it does not cover.

Most values change once or twice a year, usually on January 1 or July 1. You are allowed to cache responses, which saves requests. Two approaches work well:

• Daily cache: store responses per effective date and parameter set for one day. Simple, and accurate enough for most applications.
• Your own table: import the history once and pick up new steps by webhook. That way your software only makes a request when something actually changes.

The API sets Cache-Control: no-store so that caches on the network do not retain responses that carry your key. This does not affect caching inside your own application.