API
Alles wat op deze site staat, ook als JSON. Alleen-lezen. Vrij te gebruiken; met een sleutel ruimer.
De ingang
Alle paden hieronder staan achter dit adres.
Liever via een AI-assistent?
Dezelfde gegevens, als MCP-server.
Voeg btwzoeken.be toe in Claude of ChatGPT en vraag ernaar in gewone taal, zonder zelf een client te schrijven.
Probeer het
Kies een ingang, vul in, verstuur. Elk verzoek telt mee in de begrenzing hieronder.
Optioneel. Hij wordt niet bewaard en gaat alleen mee in het verzoek dat u hier verstuurt.
De beschrijving downloaden
OpenAPI 3.1: elke ingang, elke parameter, elk antwoord en elk schema, in een bestand.
Er valt een client mee te genereren, en hij valt in te lezen in Postman, Insomnia of Bruno.
curl -s -o openapi.json https://btwzoeken.be/api/v1/openapi.jsonHaalt u het document bij elke start op in plaats van het bij te houden, dan loopt u nooit achter op een filter die erbij komt. Dat adres telt niet mee in de begrenzing.
Wat een sleutel verandert
Zonder sleutel: vijf verzoeken per minuut en twintig per uur, geteld per IP-adres. Met sleutel: honderd per uur, geteld per sleutel. Een sleutel maakt u aan na aanmelding; hij is gratis.
- De functiehouders -- bestuurders en zaakvoerders zijn natuurlijke personen. Ze staan op de fiche in de browser en in de publieke raadpleging van de KBO; hier staan ze op een eigen adres, achter een sleutel. Het verschil tussen raadplegen en in bulk ophalen is precies het verschil dat een sleutel herstelt: begrensd, en op naam.
- E-mailadressen en telefoonnummers -- dezelfde grens als op de fiche: bij een eenmanszaak is het adres van de onderneming het adres van een mens, en dat toont de site ook alleen aan wie aangemeld is.
- De coordinaten van adressen -- de kaart zit achter een menselijkheidscontrole. Een ingang die anoniem per btw-nummer een punt teruggeeft, zou die poort langs de achterkant openzetten.
Aanmelden of een account maken om een sleutel aan te maken.
Deze API zet niets in gang
Zij leest wat er ligt. Een verzoek hier lokt geen hervalidatie bij VIES uit, geen geocodering, geen bevraging van de KBO of de Nationale Bank, en geen domeinscan. De fiche in de browser doet dat wel -- daar is een verzoek een bezoek, hier is het er een van duizend. Hoe vers de gegevens zijn, staat in /status en per onderdeel in de datumvelden.De ingangen
| Pad | Wat het teruggeeft | Uitproberen |
|---|---|---|
| /api/v1 |
De ingang van deze API
Verwijst naar de beschrijving, de uitleg en de stand van zaken. Bedoeld als vertrekpunt voor een client die alleen dit adres kent.
|
Probeer |
| /api/v1/status |
De stand van zaken
Of deze API antwoordt, en hoe vers de gegevens erachter zijn: wanneer de laatste uitgave van de KBO is ingelezen en hoeveel ondernemingen erin staan.
|
Probeer |
| /api/v1/openapi.json |
Dit document
De beschrijving van deze API, als OpenAPI 3.1.
|
Probeer |
| /api/v1/sources |
De bronnen achter deze gegevens
Welke bron welk stuk van het antwoord levert, in welk ritme ze ververst wordt, en hoeveel er in deze databank staat. Dezelfde inhoud als de bronnenpagina in de browser.
|
Probeer |
| /api/v1/companies |
Ondernemingen zoeken en filteren
Dezelfde zoekopdracht en dezelfde filters als de zoekpagina in de browser, met dezelfde sleutels. Minstens een zoekterm of een filter is verplicht: zonder beide zou het antwoord alle ondernemingen zijn.
|
Probeer |
| /api/v1/companies/{nummer} |
Een onderneming opvragen
De gegevens van een onderneming op haar btw-nummer of ondernemingsnummer.
|
Probeer |
| /api/v1/companies/{nummer}/officers |
De functiehouders van een onderneming
Bestuurders, zaakvoerders en vaste vertegenwoordigers, in de volgorde waarin de KBO ze toont. Een functiehouder is in Belgie vaker een vennootschap dan een mens; `kind` zegt welke van de twee.
|
Probeer |
| /api/v1/companies/{nummer}/annual-accounts |
De jaarrekeningen van een onderneming
Wat er bij de Balanscentrale van de Nationale Bank neergelegd is, en wat wij eruit gelezen hebben.
|
Probeer |
| /api/v1/companies/{nummer}/subsidies |
De subsidies van een onderneming
De toekenningen uit het Vlaams Subsidieregister, recentste jaar eerst.
|
Probeer |
| /api/v1/companies/{nummer}/publications |
De akten in het Belgisch Staatsblad
De akten van deze rechtspersoon in de Bijlagen bij het Belgisch Staatsblad, nieuwste eerst.
|
Probeer |
| /api/v1/companies/{nummer}/contracts |
De Europese overheidsopdrachten van een onderneming
De gunningen waarin deze onderneming als winnaar werd aangekondigd in TED, het Supplement bij het Publicatieblad van de Europese Unie. Jongste eerst.
|
Probeer |
| /api/v1/establishments/{nummer} |
Een vestigingseenheid opvragen
Een vestiging op haar vestigingsnummer, met de ondernemingen die eraan hangen.
|
Probeer |
| /api/v1/activities |
De nomenclatuur: secties en afdelingen
De boom van NACE-BEL: de secties A tot U met hun afdelingen.
|
Probeer |
| /api/v1/activities/{code} |
Een activiteitencode, met de ondernemingen die ze uitoefenen
Wat de code betekent, waar ze onder valt, welke codes eronder vallen, en wie ze uitoefent.
|
Probeer |
| /api/v1/persons/{slug} |
De mandaten van een persoon
Alles waarvan deze naam bestuurder, zaakvoerder of vaste vertegenwoordiger is.
|
Probeer |
| /api/v1/subsidies/{slug} |
Een subsidie uit het register, met wie ze kreeg
Waar /companies/{nummer}/subsidies bij een onderneming begint, begint deze bij een SUBSIDIE: wie kreeg ze, hoeveel, en in welk jaar.
|
Probeer |
| /api/v1/domains/{host} |
Het digitaal profiel van een domein
Wat er achter een domein draait en hoe het ervoor staat: DNSSEC, SPF, DMARC, een mailserver, een security.txt, en de diensten die herkend zijn -- met het bewijs erbij.
|
Probeer |
| /api/v1/technologies |
De diensten die achter Belgische domeinen draaien
Welke diensten wij ergens werkelijk waargenomen hebben, en op hoeveel gescande domeinen.
|
Probeer |
| /api/v1/technologies/{slug} |
Een dienst, met de ondernemingen die haar gebruiken
Alleen een dienst die wij ergens echt waargenomen hebben, heeft een adres. Een verzonnen sleutel is een 404 en zet geen scan in gang.
|
Probeer |
Een onderneming opvragen
De schrijfwijze van het nummer maakt niet uit: met of zonder BE, met of zonder punten.
curl -s https://btwzoeken.be/api/v1/companies/BE0400378485Zoeken en filteren
Minstens een zoekterm of een filter is verplicht.
curl -s 'https://btwzoeken.be/api/v1/companies?q=frituur&postcode=9000'De parameters
| Sleutel | Betekenis | Voorbeeld |
|---|---|---|
| q | De zoekterm: een naam, een handelsnaam of een nummer. Minstens drie tekens. | frituur |
| code | Een NACE-code om op te filteren. Werkt als voorvoegsel: 47 levert de hele detailhandel. | 5610 |
| versie |
De versie van de nomenclatuur waar de code bij hoort. Standaard de nieuwste.
2003
2008
2025
|
|
| sectie | De NACE-sectie: een letter van A tot U. | I |
| postcode | De postcode. Werkt als voorvoegsel: 90 levert alles van 9000 tot 9099. | 9000 |
| gemeente | De gemeente. Werkt als voorvoegsel. | Gent |
| rechtsvorm | Het nummer van de rechtsvorm. | |
| toestand | Het nummer van de juridische toestand. | |
| type | Het nummer van het soort onderneming. | |
| actief |
Alleen actieve (ja) of alleen stopgezette (nee) ondernemingen. Weglaten levert beide.
ja
nee
|
|
| vanaf | Alleen ondernemingen die vanaf dit jaar startten. | 2020 |
| tot | Alleen ondernemingen die tot en met dit jaar startten. | 2024 |
| sort |
Waarop gesorteerd wordt. Relevantie werkt alleen met een zoekterm.
relevantie
naam
start
nummer
stop
|
|
| dir |
De richting van de sortering.
asc
desc
|
|
| per | Aantal per pagina, van 10 tot 100. | |
| page | Het paginanummer. |
Let op meta.total_is_lower_bound. Staat die op true, dan zat het venster van de zoekmachine vol en is meta.total een ondergrens, geen telling. Zonder zoekterm telt het totaal altijd alles.
De begrenzing
Niet tegen wie iets wil opzoeken, maar tegen wat de databank plat legt.
| Onderdeel | Zonder sleutel | Met sleutel |
|---|---|---|
| Per minuut | 5 | geen aparte grens |
| Per uur | 20 | 100 |
| Geteld per | IP-adres | sleutel |
De twee vensters zonder sleutel vangen elk iets anders: vijf per minuut vangt de stoot van een script dat in een lus draait, twintig per uur vangt het gestage aftappen dat onder elke minuutgrens door glipt.
De ingang, de beschrijving en de stand van zaken tellen hier niet in mee (zestig per minuut). Een client die netjes begint, hoort daar zijn budget niet aan kwijt te zijn.
Wordt er een overschreden, dan volgt 429 met een Retry-After-kop die zegt hoelang wachten. Wie het volledige bestand wil, haalt beter de maandelijkse ZIP van de KBO op: dat is sneller dan welk aantal verzoeken ook.
De sleutel meesturen
Als kop, niet als queryparameter: die belandt in de logs van elke proxy onderweg.
curl -H 'Authorization: Bearer btwz_...' https://btwzoeken.be/api/v1/companies/BE0400378485Of, voor een client die geen bearer token kan sturen:
curl -H 'X-Api-Key: btwz_...' https://btwzoeken.be/api/v1/companies/BE0400378485Een sleutel die niet klopt of ingetrokken is, geeft 401 -- en niet stilzwijgend de publieke begrenzing. Dat laatste levert een integratie op die "soms" werkt, en dat is de moeilijkste storing om te vinden.
Herkomst en hergebruik
Open data van de KBO, hergebruik onder de voorwaarden van de FOD Economie. De voorwaarden van de KBO. Waar de gegevens vandaan komen en wanneer de laatste uitgave is ingelezen, staat op de bronnenpagina.