CBE2JSON API-documentatie

Snel aan de slag

1. Vraag je API-sleutel aan

Maak een gratis account aan (50 credits per maand, geen creditcard nodig) en genereer daarna een sleutel in je dashboard. Een sleutel bestaat uit een clientId en een secretKey.

2. Doe je eerste request

Elk endpoint verwacht een POST met een JSON-body: je inloggegevens plus een data-object. Dit voorbeeld zoekt Proximus op via het ondernemingsnummer. Punten en het BE-voorvoegsel zijn optioneel: 0202239951 en BE0202.239.951 werken ook.

curl -X POST https://api.cbe2json.be/byCBE \
  -H "Content-Type: application/json" \
  -d '{"clientId": "YOUR_CLIENT_ID", "secretKey": "YOUR_SECRET_KEY", "data": {"cbe": "0202.239.951"}}'

// Node.js 18+, as an ES module: save as first-call.mjs
const response = await fetch('https://api.cbe2json.be/byCBE', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    clientId: 'YOUR_CLIENT_ID',
    secretKey: 'YOUR_SECRET_KEY',
    data: { cbe: '0202.239.951' },
  }),
});
// Check the status first: not every error body is JSON.
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const body = await response.json();
// API version 2 wraps the enterprise in { data, meta }; version 1 returns it bare.
const company = body.data ?? body;
console.log(company.enterpriseNumber, company.denominations[0].denomination);

import requests

response = requests.post(
    "https://api.cbe2json.be/byCBE",
    json={
        "clientId": "YOUR_CLIENT_ID",
        "secretKey": "YOUR_SECRET_KEY",
        "data": {"cbe": "0202.239.951"},
    },
    timeout=10,
)
# Check the status first: not every error body is JSON.
if not response.ok:
    raise RuntimeError(f"HTTP {response.status_code}: {response.text}")
body = response.json()
# API version 2 wraps the enterprise in { data, meta }; version 1 returns it bare.
company = body.get("data", body)
print(company["enterpriseNumber"], company["denominations"][0]["denomination"])

Om op naam te zoeken, stuur je een POST naar /byDenomination met "data": {"denomination": "Proximus", "limit": 10, "offset": 0}.

Om ondernemingen op te zoeken op activiteit (NACE), postcode, gemeente, straat en huisnummer, rechtsvorm of rechtstoestand, stuur je een POST naar /search met bijvoorbeeld "data": {"zipcode": "1000", "street": "Rue de la Loi", "houseNumber": "16"}. NACE- en adresfilters moeten op dezelfde zetel of dezelfde vestigingseenheid slaan. De resultaten zijn gesorteerd op oplopend ondernemingsnummer, zodat offset en limit een stabiele paginering geven. Gebruik het om bedrijven op te zoeken of te verifiëren, bijvoorbeeld wie op een bepaald adres gevestigd is, of welke activiteitscode een leverancier heeft — de KBO Open Data-licentie sluit direct marketing uit.

/search/numbers gebruikt dezelfde filters en geeft alleen ondernemingsnummers terug, tot 1000 per pagina, in dezelfde oplopende volgorde.

CBE2JSON JavaScript & TypeScript SDK

3. Verwerk het antwoord

Een geslaagde call geeft JSON terug. Vanaf API-versie 2 heeft het antwoord de vorm { data, meta }: data bevat de onderneming (of de lijst met ondernemingen), en meta geeft de datum van de geleverde KBO-dataset, de credits die de call verbruikte en de resterende credits. Controleer eerst de HTTP-status: API-fouten geven een JSON-body zoals {"errorCode": "…", "message": "…"} terug, met een van deze codes:

byCBE verbruikt 1 credit per gevonden onderneming. byDenomination en search verbruiken 1 credit per teruggegeven onderneming. search/numbers verbruikt 1 credit per pagina met resultaten. Mislukte requests en lege resultaten verbruiken geen credits. Antwoorden vermelden je credits ook in headers: CBE2JSON-Credits-Used, -Remaining, -Limit en -Reset.

API-versies

Elke API-sleutel is gekoppeld aan een antwoordformaat, zodat de JSON die je verwerkt nooit onverwacht verandert. Nieuwe sleutels starten op de nieuwste versie; je kunt de versie van een sleutel op elk moment wijzigen in je dashboard, en weer terugzetten.

• Versie 1 — het oorspronkelijke formaat. Alle sleutels die vóór het versiebeheer zijn aangemaakt, gebruiken het.
• Versie 2 — verpakt elk antwoord in { data, meta }: data bevat de onderneming of de lijst met ondernemingen; meta geeft de datum van de dataset (dataUpdatedAt), de credits (creditsUsed, creditsRemaining, creditsLimit, creditsResetAt) en, voor byDenomination, de pagina (total, limit, offset, hasNext). byDenomination aanvaardt een limit van maximaal 100 en beantwoordt een zoekopdracht zonder resultaten met een lege lijst in plaats van een 404.

Om voor één request een andere versie te proberen, stuur je de header CBE2JSON-Version mee (bijvoorbeeld 2). Elk antwoord bevat dezelfde header, met de gebruikte versie.

Elke wijziging aan een bestaand antwoordformaat komt in een nieuwe versie. Oudere versies blijven minstens 12 maanden ondersteund na de release van een nieuwere versie, en we mailen je voordat we er een stopzetten.