Dates & history

Almost everything in this data has a period it applies to. Getting the boundaries right is most of what separates a correct integration from a subtly wrong one.

Validity periods

A versioned record carries valid_from and, if it has ended, valid_to. Both bounds are inclusive: a record with valid_to of 2025-12-31 was in force on 31 December 2025 and not on 1 January 2026.

An absent valid_to means open-ended — no end date has been published. It does not mean the record is permanent, only that nothing has been said about when it stops.

The source encodes open-ended as the date 31-12-2999. We normalise that to an absent field on the way in, so the year 2999 never reaches a response.

Querying a date

Add ?at=YYYY-MM-DD. The answer is the state in force on that date: the description that applied, the amounts that applied, and whether the code was in force at all.

Point in time

GET /v1/codes/101076?at=2019-05-01
GET /v1/codes/101076/tariffs?at=2022-03-01
GET /v1/tariffs?code=101076&at=2025-06-01

A code that existed but was not in force

If a code exists in the data but was not in force on the date you asked about, you get a 404 that says so explicitly, rather than the same message as an unknown code. They are different situations and the distinction saves a support round trip.

404

{
  "error": {
    "code": "resource_not_found",
    "message": "Code 101076 exists but was not in force on 1990-01-01."
  }
}

When the source publishes overlapping windows

For 49 of the 31,231 codes the source publishes an old long-running version and a later amendment that starts inside it, without closing the first. On a date inside that window two versions are technically in force, sometimes with different text or a different amount.

The one with the later valid_from wins — a more recent publication supersedes an earlier one. You will always get exactly one description per language and one amount per fee code. Every such overlap is historical; none reaches today.

Which date to use

For billing, use the date the care was delivered, not today and not the date of entry. That is the whole reason this parameter exists: a record entered in September describing March care must be validated against March's amounts.

History as a series

GET /v1/codes/{code}/history returns every description version and every published amount, oldest first. Nothing is ever overwritten, so the series is complete: a tariff moving from €32.84 to €33.74 is one period that ended and another that began.