Docs navigation: REST APIBase URL
Access methods

REST API

The HTTP interface for any programming language. Every dataset answers GET requests with JSON, and lists are also available as CSV.

Base URL

#

All endpoints live under https://api.quellenkontor.dev/v1. The API only speaks HTTPS and answers GET requests, plus OPTIONS for calls from the browser. The version is part of the path. Calling the base URL without a path returns a short overview with links to the catalog, OpenAPI and the docs.

Anatomy of a request

#

Every dataset has a path under /hr/; the parameters go in the address:

Schema
GET https://api.quellenkontor.dev/v1/hr/<dataset>?<parameter>=<value>&…
Authorization: Bearer <key>
TypeFormatExample
DateYYYY-MM-DDdatum=2027-01-15
Yearfour digitsjahr=2027
Numberperiod or comma as the decimal separatornetto=2500.50
Booleantrue, false, 1, 0, ja or neinprobezeit=true
Selectionone of the allowed values, case does not matterland=HE

The API rejects unknown parameters with unbekannter_parameter instead of silently ignoring them, so a typo stands out immediately. Besides the dataset's own parameters there is format (json or csv) and trennzeichen (komma or semikolon, only with CSV).

All endpoints

#
EndpointParametersReference
GET /hr/mindestlohndatumMinimum wage
GET /hr/mindestlohn/verlaufvon, bisHistory
GET /hr/mindestausbildungsverguetungbeginn, ausbildungsjahr, bestandteilApprentice pay
GET /hr/mindestausbildungsverguetung/verlaufvon, bis, bestandteilHistory
GET /hr/pflegemindestlohndatum, bestandteilCare minimum wage
GET /hr/pflegemindestlohn/verlaufvon, bis, bestandteilHistory
GET /hr/rechengroessenjahr, datumContribution ceilings
GET /hr/rechengroessen/verlaufvon, bisHistory
GET /hr/beitragssaetzedatumContribution rates
GET /hr/beitragssaetze/verlaufvon, bisHistory
GET /hr/sachbezugswertejahr, datumMeal and lodging values
GET /hr/sachbezugswerte/verlaufvon, bisHistory
GET /hr/pfaendungsfreigrenzendatum, unterhaltspflichten, nettoGarnishment exemptions
GET /hr/pfaendungsfreigrenzen/verlaufvon, bisHistory
GET /hr/uebergangsbereichdatumMidi-job zone
GET /hr/uebergangsbereich/verlaufvon, bisHistory
GET /hr/minijob-abgabendatum, bestandteilMini-job levies
GET /hr/minijob-abgaben/verlaufvon, bis, bestandteilHistory
GET /hr/kuenstlersozialabgabejahr, datum, bestandteilArtists' social levy
GET /hr/kuenstlersozialabgabe/verlaufvon, bis, bestandteilHistory
GET /hr/ausgleichsabgabejahr, datum, arbeitsplaetze, besetzt, bestandteilCompensatory levy
GET /hr/ausgleichsabgabe/verlaufvon, bis, bestandteilHistory
GET /hr/steuerfreie-betraegedatum, bestandteilTax-free amounts
GET /hr/steuerfreie-betraege/verlaufvon, bis, bestandteilHistory
GET /hr/reisekosten-inlanddatum, bestandteilTravel expenses
GET /hr/reisekosten-inland/verlaufvon, bis, bestandteilHistory
GET /hr/sfn-zuschlaegedatum, grundlohn_stunde, bestandteilNight and holiday premiums
GET /hr/sfn-zuschlaege/verlaufvon, bis, bestandteilHistory
GET /hr/dienstwagenlistenpreis*, antrieb, anschaffung, ueberlassung, entfernung_km, fahrten_monat, zuzahlung_monat, co2_g_km, reichweite_km, batterie_kwh, datumCompany car
GET /hr/einkommensteuer-eckwertejahr, datum, bestandteilBasic tax allowance
GET /hr/einkommensteuer-eckwerte/verlaufvon, bis, bestandteilHistory
GET /hr/kuendigungsfristeintritt*, zugang*, seite, probezeitNotice period
GET /hr/urlaubsansprucharbeitstage_pro_woche*, jahr, eintritt, austrittVacation entitlement
GET /hr/mutterschutztermin, geburt, fall, sswMaternity protection
GET /hr/feiertagejahr, landPublic holidays
GET /hr/arbeitstagevon*, bis*, land*, samstag, regionaleWorking days
GET /hr/regelaltersgrenzegeburtsdatum, geburtsjahr, vertrauensschutzRetirement age
GET /hr/pausenarbeitszeit_stunden*, jugendlichRest breaks
GET /datensaetzeno key neededCatalog of all datasets
GET /aenderungenno key neededChangelog
GET /statusno key neededReview status per dataset: last check, secured through, expected change
GET /openapi.jsonno key neededOpenAPI description
GET /exportnoneFull export, one request

Parameters marked with * are required.

Examples in six languages

#

All examples query the same notice period (Kündigungsfrist): start of employment on March 1, 2017, notice given by the employer, received on November 10, 2026. If you would rather work with ready-made methods, use the SDK for JavaScript or for Python.

curl

Terminal
curl "https://api.quellenkontor.dev/v1/hr/kuendigungsfrist?eintritt=2017-03-01&zugang=2026-11-10" \
  -H "Authorization: Bearer $QK_KEY"

JavaScript (fetch)

JavaScript
const url = new URL("https://api.quellenkontor.dev/v1/hr/kuendigungsfrist");
url.search = new URLSearchParams({ eintritt: "2017-03-01", zugang: "2026-11-10" }).toString();

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.QK_KEY}` },
  signal: AbortSignal.timeout(15000),
});
const daten = await res.json();
if (!res.ok) throw new Error(`${daten.fehler.code}: ${daten.fehler.nachricht}`);
console.log(daten.ende);

Python (requests)

Python
import os
import requests

r = requests.get(
    "https://api.quellenkontor.dev/v1/hr/kuendigungsfrist",
    params={"eintritt": "2017-03-01", "zugang": "2026-11-10"},
    headers={"Authorization": f"Bearer {os.environ['QK_KEY']}"},
    timeout=15,
)
daten = r.json()
if not r.ok:
    raise RuntimeError(f"{daten['fehler']['code']}: {daten['fehler']['nachricht']}")
print(daten["ende"])

PHP

PHP
<?php
$url = "https://api.quellenkontor.dev/v1/hr/kuendigungsfrist?" . http_build_query([
    "eintritt" => "2017-03-01",
    "zugang" => "2026-11-10",
]);
$kontext = stream_context_create(["http" => [
    "header" => "Authorization: Bearer " . getenv("QK_KEY"),
    "ignore_errors" => true,
    "timeout" => 15,
]]);
$daten = json_decode(file_get_contents($url, false, $kontext), true);
echo $daten["ende"] ?? $daten["fehler"]["nachricht"];

C# (.NET)

C#
using System.Net.Http.Headers;
using System.Text.Json;

using var http = new HttpClient { BaseAddress = new Uri("https://api.quellenkontor.dev/v1/") };
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("QK_KEY"));

var antwort = await http.GetAsync("hr/kuendigungsfrist?eintritt=2017-03-01&zugang=2026-11-10");
using var daten = JsonDocument.Parse(await antwort.Content.ReadAsStringAsync());
Console.WriteLine(antwort.IsSuccessStatusCode
    ? daten.RootElement.GetProperty("ende").GetString()
    : daten.RootElement.GetProperty("fehler").GetProperty("nachricht").GetString());

Java (11+)

Java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Kuendigungsfrist {
    public static void main(String[] args) throws Exception {
        HttpRequest anfrage = HttpRequest.newBuilder(URI.create("https://api.quellenkontor.dev/v1/hr/kuendigungsfrist?eintritt=2017-03-01&zugang=2026-11-10"))
            .header("Authorization", "Bearer " + System.getenv("QK_KEY"))
            .timeout(Duration.ofSeconds(15))
            .GET()
            .build();
        HttpResponse<String> antwort = HttpClient.newHttpClient()
            .send(anfrage, HttpResponse.BodyHandlers.ofString());
        System.out.println(antwort.statusCode() + " " + antwort.body());
    }
}

Response

Response
{
  "datensatz": "kuendigungsfrist",
  "eintritt": "2017-03-01",
  "zugang": "2026-11-10",
  "seite": "arbeitgeber",
  "probezeit": false,
  "betriebszugehoerigkeit_jahre": 9,
  "frist": "3 Monate zum Ende eines Kalendermonats",
  "frist_code": "monate_3_zum_monatsende",
  "fristende": "2027-02-10",
  "ende": "2027-02-28",
  "rechtsgrundlage": "§ 622 Abs. 2 Satz 1 Nr. 3 BGB",
  "hinweise": [
    "Schematische Berechnung der gesetzlichen Frist. Abweichende Fristen aus einem Tarifvertrag, auch kürzere (§ 622 Abs. 4 BGB), und längere Fristen aus dem Arbeitsvertrag sind nicht berücksichtigt.",
    "Besteht ein Betriebsrat, ist er vor jeder Kündigung anzuhören, sonst ist sie unwirksam (§ 102 Abs. 1 BetrVG). Bei einer ordentlichen Kündigung hat er eine Woche Zeit; das bei der Planung des Zugangs einrechnen.",
    "Maßgeblich ist der Tag, an dem die Kündigung zugeht. Die Kündigung braucht die Schriftform (§ 623 BGB)."
  ],
  "quelle": {
    "titel": "§ 622 BGB (Kündigungsfristen bei Arbeitsverhältnissen)",
    "url": "https://www.gesetze-im-internet.de/bgb/__622.html"
  },
  "quellen": [
    {
      "titel": "§ 622 BGB (Kündigungsfristen bei Arbeitsverhältnissen)",
      "url": "https://www.gesetze-im-internet.de/bgb/__622.html"
    },
    {
      "titel": "§ 187 BGB (Fristbeginn)",
      "url": "https://www.gesetze-im-internet.de/bgb/__187.html"
    },
    {
      "titel": "§ 188 BGB (Fristende)",
      "url": "https://www.gesetze-im-internet.de/bgb/__188.html"
    }
  ],
  "stand": "2026-09-23",
  "lizenz": "Berechnung nach den genannten Normen. Nutzung nach den Nutzungsbedingungen von Quellenkontor.",
  "zitat": "Gesetzliche Kündigungsfrist bei Eintritt am 01.03.2017 und Zugang der Kündigung am 10.11.2026, Kündigung durch den Arbeitgeber: 3 Monate zum Ende eines Kalendermonats, das Arbeitsverhältnis endet am 28.02.2027. Schematische Berechnung ohne vertragliche oder tarifliche Fristen. Rechtsgrundlage: § 622 Abs. 2 Satz 1 Nr. 3 BGB. Quelle: § 622 BGB (Kündigungsfristen bei Arbeitsverhältnissen), https://www.gesetze-im-internet.de/bgb/__622.html. Daten: Quellenkontor (quellenkontor.dev).",
  "datenstand": "2026-09-23.1"
}

OpenAPI 3.1

#

The full description is available without a key at https://api.quellenkontor.dev/v1/openapi.json. It contains every endpoint with parameters, types and examples. You can import it into Postman, Insomnia or Bruno, or generate a client for your language with the OpenAPI Generator:

Terminal
npx @openapitools/openapi-generator-cli generate \
  -i https://api.quellenkontor.dev/v1/openapi.json -g csharp -o ./quellenkontor-client

Versions and stability

#

The version is part of the path, currently /v1. Within v1, only additions happen: new datasets, new optional parameters, new fields in responses. We would only rename or remove a field, or change its meaning, in a new version, announced in the changelog. So write your code to ignore fields it does not recognize.

Timeouts and retries

#
  • Set a timeout of about 15 seconds per request.
  • Only retry on network errors and status 502, 503 and 504, with a growing delay, for example 0.3 and 0.6 seconds. That is what the SDKs do too.
  • Do not retry responses with 4xx. The request is faulty, or the quota is used up; retrying will not change that.

Calls from the browser

#

The API allows calls from any origin (CORS), so you can quickly try examples in the browser. For a real application, the key belongs on your server: proxy requests there, or cache the values. Anything that lives in the browser can be read by any visitor.

A key in frontend code is a public key. Revoke it in your account if that has happened.

Something missing or unclear? Write to us and we will extend the docs.