Quickstart

From nothing to a real response. Should take about two minutes.

1. Get a key

Create an account. A key is issued immediately — there is no approval step and no card. The Free plan allows 1,000 requests a month.

The key is shown once, at creation. We store only a hash of it, so it cannot be recovered; if you lose it, create another.

2. Make a request

Code 101076 is a consultation with an accredited GP — a good first lookup because it has descriptions in both languages, a full classification and eighteen published amounts.

curl

curl https://api.healthcodesapi.be/v1/codes/101076 \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.healthcodesapi.be/v1/codes/101076", {
  headers: { Authorization: `Bearer ${process.env.NOMEN_API_KEY}` },
});
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}
const code = await res.json();
console.log(code.description.nl);

Python

import os, requests

res = requests.get(
    "https://api.healthcodesapi.be/v1/codes/101076",
    headers={"Authorization": f"Bearer {os.environ['NOMEN_API_KEY']}"},
    timeout=10,
)
res.raise_for_status()
code = res.json()
print(code["description"]["nl"])

3. Read the response

200 OK

{
  "code": "101076",
  "category": "nomenclature",
  "active": true,
  "valid_from": "1995-09-01",
  "description": {
    "nl": "Raadpleging in de spreekkamer door een geaccrediteerde huisarts",
    "fr": "Consultation au cabinet par un médecin généraliste accrédité"
  },
  "care_setting": "ambulatory",
  "classification": {
    "chapter": { "id": "CH02", "name": { "nl": "Hoofdstuk II. …" } },
    "article": { "id": "2", "name": { "nl": "Art. 2." } }
  },
  "source": {
    "organization": "RIZIV/INAMI",
    "application_date": "2026-09-01",
    "retrieved_at": "2026-09-21T13:29:01Z"
  }
}

Note valid_to is absent: this code has no published end date. And source names the publication this answer came from, on every response.

4. Ask for money

A code's amounts are a separate resource, because there are usually several and they mean different things.

GET /v1/codes/101076/tariffs

{
  "code": "101076",
  "at": "2026-09-21",
  "data": [
    { "fee_code": 0,    "kind": "fee",           "regime": "not_applicable", "amount": "33.740000" },
    { "fee_code": 1600, "kind": "reimbursement", "regime": "standard",       "amount": "27.740000" },
    { "fee_code": 3600, "kind": "patient_share", "regime": "standard",       "amount": "6.000000"  }
  ]
}

€33.74 is the tariff, €27.74 is what the insurer reimburses, €6.00 is what the patient pays. See amounts & tariffs for the full set.

5. Ask about the past

Add ?at= to almost anything. This is a Developer-plan feature.