Van oude naar nieuwe API's
KVK introduceert nieuwe API's! Deze gaan de huidige API's vervangen. Bekijk de documentatie, lees meer over de verschillen met de oude API's en hoe je overstapt.
Waarom nieuwe API's?
- De nieuwe API's leveren data uit een vernieuwd en eenvoudiger datamodel, met een duiding die makkelijker te begrijpen en te gebruiken is.
- De nieuwe API’s houden rekening met dataminimalisatie, privacy, doelbinding en doelgebruik. Gebruik alleen gegevens die je écht nodig hebt en voor het doel waarvoor je ze nodig hebt.
- Toegang tot meer gegevens uit het Handelsregister.
- Toegang tot niet-openbare en/of afgeschermde gegevens, als je de juiste autorisatie hebt.
- De API’s verwijzen via links naar elkaar. Daardoor kun je eenvoudig aanvullende gegevens opvragen. Ook bij meerdere aanvragen tegelijk blijven de gegevens snel beschikbaar, volledig en betrouwbaar.
Oude en nieuwe API's
Drie API's worden op den duur uitgefaseerd. Je kunt ze voorlopig nog gebruiken, maar we raden je aan om alvast over te stappen op de nieuwe API's.
| Oude API | Nieuwe API |
|---|---|
| KVK Handelsregister Zoeken (V2) | KVK Handelsregister Zoeken (V3) |
| KVK Handelsregister Basisprofiel | KVK Handelsregister Organisatie |
| KVK Handelsregister Vestigingsprofiel | KVK Handelsregister Vestigingen |
De verschillen
Zoeken V2 versus Zoeken V3
De werkwijze van de Zoeken API is hetzelfde gebleven.
- De eerste stap is nog steeds het opzoeken van de inschrijving (KVK-nummer) waarvoor je de bevraging wil uitvoeren.
- Bij correcte invoer van de zoekparameters levert de zoekopdracht een output (resultaat) op. Onder andere het KVK-nummer en/of vestigingsnummer.
- Met deze gegevens stel je vast of je met de juiste inschrijving te maken hebt.
- Met het KVK-nummer haal je vervolgens meer informatie op over de inschrijving.
- Met de links in de Zoeken API roep je direct de juiste API aan. Bijvoorbeeld Vestigingen.
Nieuw
Een aantal datavelden zijn hernoemd en er zijn nieuwe datavelden toegevoegd. Het volledige overzicht staat beschreven bij de Zoeken V3 documentatie.
Basisprofiel versus Organisatie
De Basisprofiel API levert algemene gegevens, eigenaar-gegevens, hoofdvestigingsinformatie en details over verschillende vestigingen (overlap met de Vestigingsprofiel API).
De output van de nieuwe Organisatie API is beperkt tot de kern van de inschrijving: de maatschappelijke activiteit, onderneming en (niet-natuurlijke) persoon. Dit sluit beter aan bij de principes van privacy, dataminimalisatie, efficiëntie en beheer.
Informatie over de (hoofd)vestiging wordt niet meer direct meegeleverd, maar kan via een automatische link naar Vestigingen API opgevraagd worden.
Het is mogelijk om gericht gegevens op te vragen door een specifiek onderdeel van de API te bevragen. Je kunt bijvoorbeeld uitsluitend de ondernemingsgegevens ophalen door het endpoint af te sluiten met /onderneming. Dit werkt op dezelfde manier voor zowel de maatschappelijke activiteit als de (niet natuurlijke) persoon.
Vestigingsprofiel versus Vestigingen
Met de Vestigingsprofiel API haal je vestigingsinformatie op met het vestigingsnummer.
Bij de nieuwe Vestigingen API moet je ook het KVK-nummer meegeven. Doe je dit niet, dan kan het zo zijn dat de verkeerde actieve vestiging wordt teruggegeven. Bijvoorbeeld wanneer er een overdracht van een vestiging heeft plaatsgevonden.
Maak je gebruik van de Zoeken V3 API? Dan wordt het KVK-nummer automatisch opgenomen in de link. Maak je nog geen gebruik van de Zoeken API? Dan moet je het KVK-nummer eerst zelf opzoeken via Zoeken V3, voordat je de vestigingsinformatie kunt ophalen.
Mappingoverzicht
Het mappingoverzicht (Excel-bestand) toont welke gegevens in de oude API's beschikbaar waren en waar je deze in de nieuwe API's kunt terugvinden. En welke nieuwe datavelden zijn toegevoegd.
Kosten
| Oude API | Prijs | Nieuwe API | Prijs |
|---|---|---|---|
| Zoeken V2 | Gratis | Zoeken V3 | Gratis |
| Basisprofiel - exclusief hoofdvestigingsinformatie | € 0,02 | Organisatie | € 0,02 |
| Basisprofiel - inclusief (hoofd)vestigingsinformatie | € 0,02 | Organisatie en Vestigingen mét (hoofd)vestigingsinformatie | € 0,04 |
| Vestigingsprofiel | € 0,02 | Vestigingen | € 0,02 |
| Functionarissen | € 2,93 |
Documentatie nieuwe API's
Veelgestelde vragen
Gebruik hiervoor het Mappingoverzicht in combinatie met de documentatie van de afzonderlijke API's.
Test de API's gratis op onze testomgeving. Tevreden? Dan kun je overstappen naar de productieomgeving.
Swagger UI
Nee, dat is op dit moment niet mogelijk. De nieuwe API’s gebruiken andere definities en een gewijzigde inhoud van de datavelden.
Het is niet mogelijk om Zoeken V2 te gebruiken met de nieuwe API's, omdat links, definities en meldingen zijn gewijzigd.
De oude API's blijven voorlopig beschikbaar. Je ontvangt een bericht wanneer deze worden uitgefaseerd.
De naam API Organisatie sluit beter aan bij het type informatie dat wordt geleverd. De API bevat gegevens over verschillende soorten organisaties: publieke organisaties (overheden), private organisaties (bedrijven/ ondernemingen) en maatschappelijke organisaties (stichtingen en verenigingen). De term organisatie dekt daarmee de volledige inhoud van de API.
Wanneer één van de API's niet functioneert, is dat meestal het gevolg van een storing bij KVK. Omdat alle API’s op dezelfde databron zijn aangesloten, zullen in zo’n situatie alle API’s tijdelijk niet beschikbaar zijn.
Er wordt nog een extra parameter toegevoegd die aansluit op het Privacy-by-Design-principe. Deze parameter is bedoeld voor afnemers die autorisatie hebben en een beperkter deel van de niet-openbare/afgeschermde data willen ophalen.
Er volgen nog technische wijzigingen om volledig te voldoen aan de NL Design API rules.
- Foutmeldingen worden duidelijker.
- Dankzij de OAS 3.2-specificatie kun je straks de API’s sneller en eenvoudiger aansluiten.