CBE2JSON API Documentation

Quickstart

1. Get your API key

Create a free account (50 credits a month, no credit card), then generate a key in your dashboard. A key is a clientId and a secretKey.

2. Make your first request

Every endpoint takes a POST with a JSON body: your credentials plus a data object. This example looks up Proximus by its enterprise number. Dots and the BE prefix are optional: 0202239951 and BE0202.239.951 work too.

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"])

To search by name, POST to /byDenomination with "data": {"denomination": "Proximus", "limit": 10, "offset": 0}.

To look companies up by activity (NACE), postcode, municipality, street and house number, legal form or legal situation, POST to /search with, for example, "data": {"zipcode": "1000", "street": "Rue de la Loi", "houseNumber": "16"}. NACE and address filters must match the same registered office or establishment. Results are ordered by ascending enterprise number, so offset and limit page through them in a stable order. Use it to look up or verify companies, for instance who is registered at an address or whether a supplier has a given activity code — the KBO Open Data licence excludes direct marketing.

/search/numbers takes the same filters and returns only enterprise numbers, up to 1000 per page, in the same ascending order.

CBE2JSON JavaScript & TypeScript SDK

3. Handle the response

A successful call returns JSON. From API version 2, the response is { data, meta }: data holds the enterprise (or the list of enterprises), and meta gives the date of the CBE dataset served, the credits the call used and the credits left. Check the HTTP status first: API errors come with a JSON body such as {"errorCode": "…", "message": "…"}, using one of these codes:

byCBE uses 1 credit per enterprise found. byDenomination and search use 1 credit per enterprise returned. search/numbers uses 1 credit per page with results. Failed requests and empty results use no credits. Responses also carry your credits in headers: CBE2JSON-Credits-Used, -Remaining, -Limit and -Reset.

API versions

Each API key is pinned to a response format, so the JSON you parse never changes under you. New keys start on the latest version; you can switch a key in your dashboard at any time, and switch back.

• Version 1 — the original format. Every key created before versioning uses it.
• Version 2 — wraps every response in { data, meta }: data holds the enterprise or the list of enterprises; meta gives the dataset date (dataUpdatedAt), the credits (creditsUsed, creditsRemaining, creditsLimit, creditsResetAt) and, for byDenomination, the page (total, limit, offset, hasNext). byDenomination accepts a limit of at most 100 and answers a search without results with an empty list instead of a 404.

To try another version for a single request, send the CBE2JSON-Version header (for example 2). Every response carries the same header, naming the version it used.

Any change to an existing response format ships as a new version. Older versions stay supported for at least 12 months after a newer one is released, and we email you before one is retired.