API bedrijfsgegevens

Nummo API

Haal Belgische bedrijfsgegevens op in je eigen software: KBO-gegevens, kerncijfers uit de jaarrekeningen en de Peppol-status, via een eenvoudige REST API met JSON.

Neem het API-plan OpenAPI-beschrijving

Overzicht

Wat je krijgt

Gegevens uit de Kruispuntbank van Ondernemingen (KBO) voor elke Belgische onderneming.
Kerncijfers en ratio's uit de jaarrekeningen die bij de Nationale Bank zijn neergelegd.
De Peppol-status, rechtstreeks uit het Peppol-netwerk.
Zoeken op naam, nummer, straat of gemeente.

Alle antwoorden zijn JSON met Engelse veldnamen. De API is enkel om te lezen. Nummo is geen officiële bron: bij twijfel geldt altijd de bron zelf.

Wil je Nummo liever in Claude of ChatGPT gebruiken, zonder zelf te programmeren? Koppel Nummo aan je AI-assistent.

Aan de slag

Aanmelden met een sleutel

De API zit in het API-plan. Daarmee maak je op je profiel tot 5 sleutels; ze werken zolang het plan loopt. Je ziet een sleutel maar één keer: kopieer hem meteen en bewaar hem zoals een wachtwoord. Wij bewaren enkel een onleesbare vingerafdruk van de sleutel.

Stuur de sleutel mee in de header Authorization (of in X-Api-Key):

curl -H "Authorization: Bearer $NUMMO_KEY" \
  https://www.nummo.be/api/v1/companies/0999001020

Gebruik de sleutel enkel op je eigen server, niet in code die in de browser van je bezoekers draait. Lekt een sleutel toch uit, trek hem dan in op je profiel en maak een nieuwe.

REST API met JSON

Endpoints

Basisadres: https://www.nummo.be/api/v1

Oproep	Wat je krijgt
`GET /companies/{number}`	Gegevens uit de KBO: naam, rechtsvorm, status, zetel, activiteiten (NACE), aantal vestigingen en contactgegevens. Met ?lang=nl, fr of en kies je de taal van de omschrijvingen.
`GET /companies/{number}/financials`	Kerncijfers uit de neergelegde jaarrekeningen: omzet, brutomarge, winst, eigen vermogen, personeel, schulden en ratio's. Met ?years=1 tot 10 (standaard 5).
`GET /companies/{number}/peppol`	Staat de onderneming op Peppol, onder het ondernemingsnummer (0208) en het btw-nummer (9925)?
`GET /search?q=...`	Zoeken op naam, nummer, straat of gemeente. Met ?limit=1 tot 50 (standaard 20).
`GET /openapi.json`	De volledige beschrijving van de API in OpenAPI 3.1. Zonder sleutel.

Het ondernemingsnummer mag met of zonder punten en met of zonder BE: 0999001020, 0999.001.020 en BE0999001020 werken allemaal.

curl

Voorbeelden

# Een onderneming
curl -H "Authorization: Bearer $NUMMO_KEY" "https://www.nummo.be/api/v1/companies/0999001020?lang=fr"

# Kerncijfers van de laatste 3 boekjaren
curl -H "Authorization: Bearer $NUMMO_KEY" "https://www.nummo.be/api/v1/companies/0999001020/financials?years=3"

# Peppol-status
curl -H "X-Api-Key: $NUMMO_KEY" "https://www.nummo.be/api/v1/companies/0999001020/peppol"

# Zoeken
curl -H "Authorization: Bearer $NUMMO_KEY" "https://www.nummo.be/api/v1/search?q=bakkerij%20gent&limit=5"

Antwoord voor een onderneming

{
  "enterprise_number": "0999001020",
  "formatted": "0999.001.020",
  "vat_number": "BE0999001020",
  "type": "legal_entity",
  "name": "Bakkerij De Zoete Korst BV",
  "abbreviation": null,
  "other_names": [
    { "name": "Zoete Korst", "type": "commercial_name", "language": "nl" }
  ],
  "status": "active",
  "legal_form": { "code": "015", "description": "Besloten vennootschap" },
  "legal_situation": "Normale toestand",
  "start_date": "1985-01-01",
  "stop_date": null,
  "registered_office": {
    "street": "Veldstraat", "house_number": "10", "box": "2",
    "postal_code": "9000", "municipality": "Gent", "country": "België"
  },
  "activities": [
    { "nace_code": "10.710", "version": "2025", "description": "Vervaardiging van brood en van vers banketbakkerswerk", "main": true }
  ],
  "branches_count": 3,
  "contact": { "website": "www.bakkerijdezoetekorst.example", "email": null, "phone": null },
  "nummo_url": "https://www.nummo.be/bakkerij-de-zoete-korst-bv-0999001020"
}

Antwoord voor een eenmanszaak

{
  "enterprise_number": "0999008047",
  "formatted": "0999.008.047",
  "type": "natural_person",
  "status": "active",
  "legal_form": null,
  "start_date": "2005-06-15",
  "stop_date": null,
  "registered_office": { "postal_code": "9070", "municipality": "Destelbergen" },
  "activities": [ ... ]
}

Grenzen

Limieten

Met het API-plan 25.000 oproepen per kalendermaand voor al je sleutels samen, en hoogstens 2.500 per dag. Oproepen naar /search tellen enkel mee voor de daglimiet, niet voor het maandquotum. De dagteller springt om middernacht (Belgische tijd) terug op nul, de maandteller op de eerste van de maand.
Hoogstens 60 oproepen per minuut per sleutel.
Elk antwoord bevat de headers X-RateLimit-Limit en X-RateLimit-Remaining (maandquotum) en X-RateLimit-Daily-Limit en X-RateLimit-Daily-Remaining (daglimiet).
Ga je over een limiet, dan krijg je 429 met een header Retry-After.

Heb je meer dan 25.000 oproepen per maand nodig? Laat het ons weten via de help, dan maken we een voorstel op maat. Naar de help

HTTP

Foutmeldingen

Bij een fout krijg je een HTTP-status en een JSON-object met een vaste code en een uitleg in het Engels:

{
  "error": {
    "code": "invalid_number",
    "message": "Not a valid Belgian enterprise number. ..."
  }
}

Status	Code	Betekenis
`400`	`invalid_number, invalid_parameter`	Geen geldig ondernemingsnummer, of een parameter buiten de grenzen.
`401`	`missing_key, invalid_key`	Geen sleutel meegestuurd, of een sleutel die we niet kennen.
`403`	`key_revoked, api_plan_required`	De sleutel is ingetrokken, of het account heeft geen lopend API-plan.
`404`	`not_found, not_available, no_financials`	Onbekend of verborgen nummer, geen jaarrekeningen voor een natuurlijk persoon, of geen jaarrekeningen gevonden.
`429`	`rate_limited, daily_limit_reached, monthly_quota_exceeded`	Te veel oproepen: per minuut, per dag of per maand. De header Retry-After zegt hoeveel seconden je moet wachten.
`503`	`service_unavailable`	De API is tijdelijk niet beschikbaar.
`504`	`upstream_timeout`	Het Peppol-netwerk antwoordde niet op tijd.

GDPR

Privacy

De KBO bevat ook eenmanszaken van natuurlijke personen. Daar gaan we zorgvuldig mee om, ook in de API.

Eenmanszaken (natuurlijke personen): geen naam, geen straat, geen contactgegevens en geen vestigingen. Je krijgt enkel het nummer, de status, de rechtsvorm, de data, de postcode en gemeente, en de activiteiten. Zoeken op naam vindt ze niet, en er zijn geen jaarrekeningen.
Ondernemingen die gevraagd hebben om hun gegevens af te schermen: de naam wel, maar van het adres enkel postcode en gemeente, en geen contactgegevens.
Ondernemingen die gevraagd hebben om niet getoond te worden: die bestaan voor de API niet (404).

Gebruik je de gegevens voor direct marketing of profilering, dan ben jij verantwoordelijk voor de naleving van de GDPR. Privacybeleid

CORS

Van de browser uit

De API staat CORS toe voor GET-oproepen van elk domein, handig voor interne tools en prototypes. Zet een sleutel nooit in een publieke website: iedereen kan hem daar lezen. Antwoorden worden niet gecachet (Cache-Control: private, no-store).

Prijzen

API-plan

€ 999 per jaar, excl. btw

25.000 oproepen per maand per account, hoogstens 2.500 per dag
Zoekopdrachten tellen niet mee voor het maandquotum
Tot 5 sleutels, bijvoorbeeld voor test en productie
Nummo Pro inbegrepen, voor wie ook op de website werkt
Factuur met btw, ook via Peppol

Uitproberen

De voorbeelden hierboven tonen elke oproep en elk antwoord, en de OpenAPI-beschrijving kan je zonder sleutel bekijken. Sleutels maak je met het API-plan: zonder plan werkt de API niet.

Maak een API-sleutel OpenAPI-beschrijving