Controleren of een bedrijf is uitgeschreven

De twee velden die het antwoord geven

Er is geen apart statusveld met vijf mogelijke waarden. Er zijn twee velden, en samen dekken ze de gevallen die je in de praktijk tegenkomt.

isActive is een boolean. true betekent dat de inschrijving in het Handelsregister bestaat en niet is beëindigd. false betekent dat de inschrijving is uitgeschreven, bijvoorbeeld na opheffing, na afronding van een faillissement, of na een fusie waarbij de verdwijnende vennootschap ophoudt te bestaan.

insolvency bevat informatie over een lopende insolventieprocedure, en is leeg wanneer er niets speelt. Dat is een andere vraag dan uitschrijving. Een bedrijf in faillissement staat nog gewoon ingeschreven, met isActive: true, terwijl de curator het beheer voert.

Beide velden komen uit de KVK open dataset. Er is geen apart veld met de datum van uitschrijving, dus je kunt uit de response niet aflezen hoe lang een inschrijving al beëindigd is. Wil je dat weten, dan moet je het zelf vastleggen op het moment dat je de wijziging waarneemt.

De controle zelf

Eén call:

curl "https://api.kvkbase.nl/v1/lookup/68750110" \
  -H "Authorization: Bearer YOUR_API_KEY"

Wil je alleen weten of een nummer bestaat, zonder profieldata, dan is de verify-route lichter:

curl "https://api.kvkbase.nl/v1/verify/68750110" \
  -H "Authorization: Bearer YOUR_API_KEY"

Controleer je een heel klantenbestand, doe dat dan gebundeld in plaats van in een lus:

curl -X POST "https://api.kvkbase.nl/v1/lookup/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kvkNumbers":["68750110","33014286"]}'

Bij een bestand van duizenden klanten is het quotum je begrenzing, niet de rate limit: Starter geeft 1.000 lookups per maand, Pro 5.000. Een maandelijkse hercontrole van vijfduizend klanten past dus precies in Pro en nergens anders in. Loopt het over, dan krijg je QUOTA_EXCEEDED en niet stilletjes verouderde data.

Een fout die makkelijk te maken is: NOT_FOUND en isActive: false in dezelfde catch-tak afhandelen. Het eerste is een HTTP 404 met een foutcode, het tweede is een geslaagde 200 met data erin. Als je code beide als “bedrijf bestaat niet” toont, kan de gebruiker niet zien of hij een typefout maakte of een verouderd nummer gebruikte, en die twee vragen om een ander vervolg.

Waarom de cache hier wél uitmaakt

Op de meeste pagina’s is de cache van 24 uur een detail. Voor deze vraag is het de kern.

Wij cachen gegevens van actieve bedrijven 24 uur. Dat betekent dat een bedrijf dat vanochtend is uitgeschreven, in jouw response nog steeds isActive: true kan hebben. Daar bovenop komt de vertraging van het register zelf, dat een beëindiging pas verwerkt nadat die is doorgegeven en administratief afgehandeld.

De praktische conclusie: een isActive-check is uitstekend voor onboarding, debiteurenbeheer en het opschonen van een CRM. Voor het moment waarop je geld overmaakt aan een partij waarvan je vermoedt dat het misgaat, is het een signaal en geen garantie. Wie dat hard nodig heeft, kijkt naar het Centraal Insolventieregister, dat sneller is voor precies dat ene gegeven.

Bouw je een monitoringflow, lees dan company status monitoring voor het opzetten van periodieke checks zonder je quotum op te branden.

Wat je met een negatief antwoord doet

De fout die het vaakst gemaakt wordt, is isActive: false behandelen als een fatale fout in een formulier. Dat is het zelden.

• Bij nieuwe onboarding: blokkeren is redelijk. Iemand die zich met een uitgeschreven KVK-nummer aanmeldt, heeft ofwel een oud nummer bij de hand of doet iets dat je niet wilt.
• Bij een bestaande klant: niet blokkeren, maar markeren. Bedrijven schrijven zich uit bij een herstructurering en gaan onder een nieuw nummer verder. Een openstaande factuur wil je gewoon innen.
• Bij een fusie: het oude nummer wordt inactief en de rechten gaan over op de verkrijgende partij. Je klant bestaat nog, alleen onder een ander nummer. Dat verband zit niet in de response, dus dat moet een mens uitzoeken.

Log bij elke statuswijziging die je detecteert de datum en de vorige waarde. Zonder die geschiedenis weet je bij het volgende debiteurenoverleg niet of een klant gisteren is uitgeschreven of drie jaar geleden, en dat verschil bepaalt wat je nog kunt doen.