Germany Payroll API: Interfaces vs. Reference Values

What a Germany payroll API delivers

A payroll interface mainly moves data your own company has already generated: employee master data (Stammdaten), the results of a payroll run as accounting entries for the general ledger, and filings sent to health insurers (Krankenkassen), the tax office and the accident insurance carrier (Berufsgenossenschaft). It connects systems that already know which rates and thresholds apply.

What it usually does not provide is an independently queryable, sourced list of those exact rates and thresholds. Where the pension insurance contribution rate or a contribution ceiling comes from stays a configuration detail of the provider, not part of the interface itself.

A widely used provider illustrates this well. Sage describes the interfaces of its Business Cloud payroll product (Sage Business Cloud Lohnabrechnung) as a way to transfer data securely to accounting software such as Sage ERP or Sage 50, plus an accounting export for Sage and DATEV, Germany's dominant tax-advisor software. Details are on the vendor's own page, Sage: interfaces in German payroll.

What a typical interface carries

• Master data: employee number, tax ID, social insurance number, bank details, cost center, start date.
• Accounting entries: wage types and cost-center postings for the general ledger, often in the DATEV format used by German tax advisors.
• Filings and exports: social insurance filings to health insurers, wage tax filings to the tax office, contribution statements for the accident insurance carrier.
• What is usually missing: a dedicated, versioned source for the underlying official values, each with a valid-from date and evidence.

The Sage example: an interface for accounting, not for reference values

Sage's own description of its payroll interfaces names three goals: transfer data securely, avoid errors from duplicate manual entry, and save time. According to the vendor's page, what gets transferred to the connected accounting system are pay statements, tax information and data relevant to social insurance.

What matters for this article is what that description does not cover: a way to query the contribution rates or calculation figures themselves, independent of a running payroll cycle, with a legal basis and a reference date. That is not a criticism of Sage, but of what this kind of interface is built for: it connects payroll and accounting, not statute and software.

If you only run payroll for your own company and use an all-in-one product such as Sage, DATEV or Lexware end to end, the provider usually maintains the underlying values for you as part of the license. The sections below are mainly for teams that build their own software, serve several clients, or have to document where a value comes from independent of a single vendor.

Why official reference values still need a source of their own

Every payroll run needs figures that come from statutes and ordinances, not from your own books: the minimum wage, contribution ceilings, contribution rates, in-kind values and other calculation figures. These figures change constantly, mostly at year-end but sometimes mid-year, and each one has its own valid-from date.

A payroll interface assumes these values are already configured in the system. Anyone who maintains them directly, for example because they are building their own payroll logic, serving several clients with different reference dates, or running a retroactive correction for a past month with the values that applied then, needs a second source specialized in reference values. The solution page on an API for German payroll software and payroll bureaus shows how payroll software can pull calculation figures, contribution rates and in-kind values this way.

The difference shows in the details. An accounting interface usually only knows the current state. A reference-value API such as Quellenkontor's returns every value for any reference date since 2015, with its legal basis, its source, and a field that shows whether the value is already final or still provisional.

History and retroactive corrections: more than the current state

A retroactive correction for a past month needs the value that applied in that month, not today's value. A payroll interface such as Sage's usually only knows the current state of the connected systems, while a reference-value API returns every reference date since 2015.

A single query for January 1, 2026 returns the contribution ceilings, and the same query with a date from an earlier year returns the values that applied then, each with its own legal basis and source. The /verlauf endpoint bundles every stage of a dataset since 2015 into one call, and the parameters von (from) and bis (to) narrow the period. The reference-date logic is documented on the page about reference dates and validity.

For payroll bureaus with several clients or tax years, this is often the real reason for a second source: not because the existing software is wrong, but because it was not built to look up historical reference dates independent of a running payroll cycle.

Example values every German payroll run needs

Payroll interface versus reference-value API

If you are building your own payroll logic

If you build your own payroll logic, for example for a niche such as mini-jobs, short-time work (Kurzarbeit) or a specific industry model, you need the official values from the start as an input to your code, not only at the end as an accounting entry. A reference-value API takes the role that an internally maintained table of statutes would otherwise have.

The difference from a finished payroll product such as Sage, DATEV or Lexware is the starting point: those vendors maintain values for their own, closed calculation. A reference-value API returns the same values openly for any calculation you build yourself, with a CSV export for spreadsheets and an SDK for Node.js or Python.

That makes it possible to calculate with the values that will apply on a future start date already during the proposal or planning stage, even while they are only an adopted but not yet effective stage, using the field naechster_wert (next value).

CSV for payroll bureaus without their own development

Not every payroll bureau needs a programming interface. If you only look up an official value occasionally or keep your own table for recordkeeping, the CSV export is often enough, without writing a line of code.

The history of every dataset can be downloaded with format=csv, and trennzeichen=semikolon (delimiter=semicolon) gives semicolons and decimal commas for a German-locale Excel. For a single payroll bureau with a few clients, that is often all you need. A programming interface pays off once values are meant to flow automatically into your own software without a manual export.

How to add this to an existing payroll setup

The existing software stays responsible for master data, accounting entries and filings, which is exactly what it is built for. A reference-value API is added as a narrow, additional source, only for the figures that come from law and administration.

In practice this means querying values by reference date instead of hardcoding them in code or a spreadsheet, and storing them with their valid-from date in your own configuration. A daily query is enough to stay current, or, from the Pro plan on, a webhook that reports every new or changed stage automatically.

A good starting point is a parallel run: read values only and compare them with the figures already stored in your system, before the reference-value API feeds production calculations. That surfaces discrepancies, for example because a value in the existing system was outdated, before they affect a real payroll run.

A free key, no credit card required, is enough for a first test: sign up for free.

Query calculation figures for a year

$ curl "https://api.quellenkontor.dev/v1/hr/rechengroessen?jahr=2026" \
    -H "Authorization: Bearer $QK_KEY"

# Excerpt of the response
{
  "jahr": 2026,
  "bbg_kv_monat": 5812.5,
  "bbg_rv_west_monat": 8450,
  "gueltig_ab": "2026-01-01",
  "rechtsgrundlage": "Sozialversicherungsrechengrößen-Verordnung 2026 vom 24.11.2025 (BGBl. 2025 I Nr. 278)"
}

Pull values into your own configuration

import { Quellenkontor } from "@quellenkontor/sdk";

const qk = new Quellenkontor(process.env.QK_KEY);

// Store reference values once in your own configuration, booking entries and
// filings stay the job of the existing payroll software.
const rechengroessen = await qk.hr.rechengroessen({ jahr: 2026 });
const beitragssaetze = await qk.hr.beitragssaetze({ datum: "2026-07-01" });
await konfiguration.speichern("rechengroessen", rechengroessen);
await konfiguration.speichern("beitragssaetze", beitragssaetze);

When an extra source for reference values pays off

• You serve several clients or customers with different reference dates and histories.
• You build your own payroll logic or reporting module instead of only operating an all-in-one product.
• You need retroactive corrections using the values that actually applied in a past month.
• You want an automatic notice as soon as a value changes, instead of tracking ordinances yourself.
• You have to show auditors or customers which statute a value used in your system came from.
• You want to reuse values in your own spreadsheet without retyping them by hand.