Documentation

A REST API over Belgian healthcare nomenclature: codes, bilingual descriptions, classification, tariffs, reimbursements, and the history of all of them.

GET https://api.healthcodesapi.be/v1/codes/101076

200 OKapplication/json

{
  "code": "101076",
  "description": {
    "nl": "Raadpleging in de spreekkamer door een geaccrediteerde huisarts",
    "fr": "Consultation au cabinet par un médecin généraliste accrédité"
  },
  "valid_from": "1995-09-01",
  "active": true,
  "chapter": "CH02"
}

Interactive referenceTry any endpoint in the browser openapi.jsonOpenAPI 3.1, generated from the handlers QuickstartFrom nothing to a real response

What you get

31,231 nomenclature codes, each with a Dutch and a French description as published, a category, a validity period and a place in the chapter/article structure.
1.7 million published amounts. Tariffs, reimbursements and patient co-payments, each labelled with what kind of amount it is and which reimbursement regime it applies to.
Full history. Every versioned fact keeps the period it applied to, so ?at=2022-03-01 answers what was true then rather than what is true now.
A change feed with before and after values and the date each change took effect.

Conventions

These hold everywhere, so they are worth reading once.

Authentication is a bearer token: Authorization: Bearer hcapi_live_….
Collections return { data, pagination }. Single resources return the object directly.
Dates are ISO-8601 (YYYY-MM-DD). Validity ranges are inclusive at both ends, and an absent valid_to means open-ended.
Amounts are strings in EUR, with the precision the source published. They are money, so they are never floats, and 0.00 is a value, not an absence.
Errors all share one envelope with a stable machine-readable code.

Every collection

Two keys, always in this order. Single resources return the object on its own.

"data": [ … ]

The rows, in the order the endpoint documents.

"pagination": { next_cursor, has_more }

Absent next_cursor means this was the last page.

Every failure

One envelope, one stable machine-readable code. Branch on the code, show the message.

402application/json

{
  "error": {
    "code": "subscription_required",
    "message": "This plan does not include …"
  }
}

The message is for a person. The code is for your switch statement.

Start here

QuickstartFrom nothing to a real response Dates and historyThe part most people get wrong Amounts and tariffsWhy one code has eighteen numbers