docs-Documentation

Overview

Overzicht

Quickstart

Snelstart

Testing the APIs

Test de API's

Release notes

Certificates

Certificaten

Documentation

docs-API Reference

Zoeken

Basisprofiel

Vestigingsprofiel

Naamgeving

Mutatieservice

API Reference

docs-Open data

Open Dataset Basis Bedrijfsgegevens

Open dataset Jaarrekeningen

Open data

intro

<p>Een KVK API werkt als interface tussen je softwareapplicaties en het KVK Handelsregister. Het zorgt ervoor dat de twee met elkaar kunnen communiceren. Via een API-key krijg je toegang tot informatie in het Handelsregister.</p>

Wat zijn de voordelen van een KVK API?

<h2>Wat zijn de voordelen van een KVK API?</h2><ul><li data-list-item-id="e2cd819af220e1152b890523119551e8e"><strong>Automatisch aanvullen</strong>: haal direct actuele informatie op uit het Handelsregister binnen je eigen CRM-systeem, website of financiële pakket. De gegevens worden automatisch aangevuld (prefill).</li><li data-list-item-id="ee15f4edd337f9516d7add739cf0dfc20"><strong>Controleren</strong>: controleer zakelijke klanten op KVK-nummer, adresgegevens, SBI en werkzame personen.</li></ul><h2 id="available-apis">Welke API's zijn er?</h2><h3>KVK Handelsregister Zoeken</h3><p>Met de Zoeken API haal je het KVK-nummer van een inschrijving op. Aanvullende gegevens vraag je vervolgens op met een van de andere API's.</p><h3>KVK Handelsregister Basisprofiel</h3><p>Zoek basisgegevens van inschrijvingen op met het KVK-nummer. Bijvoorbeeld maatschappelijke activiteit, gegevens eigenaar/ hoofdvestiging, en een lijst van de vestigingen.</p><h3>KVK Handelsregister Vestigingsprofiel</h3><p>Zoek specifieke informatie van inschrijvingen op met het vestigingsnummer. Bijvoorbeeld algemene gegevens, activiteiten en bezoek- en postadres.</p><h3>KVK Handelsregister Naamgeving</h3><p>Gebruik het KVK-nummer om handelsnamen van een inschrijving op te halen. Bijvoorbeeld statutaire naam, handelsnamen en niet-commerciële naam.</p>

Hoe gebruik je een KVK AkPI?

<h2 id="using-the-apis">Hoe gebruik je een KVK API?</h2><p>KVK Handelsregister Basisprofiel en Vestigingsprofiel leveren maximaal één registratie per verzoek. Als er meerdere registraties zijn, dan wordt het eerste resultaat getoond. Gebruik een combinatie van velden om het zoeken zo specifiek mogelijk te maken. Bijvoorbeeld:</p><ul><li>KVK-nummer en vestigingsnummer</li><li>KVK-nummer en RSIN</li><li>KVK-nummer en type (hoofdvestiging, nevenvestiging en/of rechtspersoon)</li></ul><p>Gebruik voor free format zoeken de overige inputparameters (bijvoorbeeld handelsnaam of straatnaam).</p>

datamodel

<h2 id="data-model">Datamodel</h2><p>De Zoeken API heeft 2 aparte entiteiten die verschillen in de property "type".</p><ul><li>Vestiging</li><li>Rechtspersoon</li></ul><h3>Voorbeeld rechtspersoon met de Zoeken API:</h3><div><pre><code class="language-json">{
  "pagina": 1,
  "resultatenPerPagina": 10,
  "totaal": 1,
  "resultaten": [
    {
      "kvkNummer": "69599068",
      "naam": "Test Stichting Bolderbast",
      "adres": {
        "binnenlandsAdres": {
          "type": "bezoekadres",
          "straatnaam": "Oosterwal",
          "plaats": "Lochem"
        }
      },
      "type": "rechtspersoon",
      "links": [
        {
          "rel": "basisprofiel",
          "href": "https://api.kvk.nl/test/api/v1/basisprofielen/69599068"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "https://api.kvk.nl/test/api/v2/zoeken?kvknummer=69599068&amp;pagina=1&amp;resultatenperpagina=10"
    }
  ]
}
</code></pre></div><h3>Voorbeeld vestiging met de Zoeken API:</h3><div><pre><code class="language-json">{
  "pagina": 1,
  "resultatenPerPagina": 10,
  "totaal": 1,
  "resultaten": [
    {
      "kvkNummer": "68750110",
      "vestigingsnummer": "000037178598",
      "naam": "Test BV Donald",
      "adres": {
        "binnenlandsAdres": {
          "type": "bezoekadres",
          "straatnaam": "Hizzaarderlaan",
          "plaats": "Lollum"
        }
      },
      "type": "hoofdvestiging",
      "links": [
        {
          "rel": "basisprofiel",
          "href": "https://api.kvk.nl/test/api/v1/basisprofielen/68750110"
        },
        {
          "rel": "vestigingsprofiel",
          "href": "https://api.kvk.nl/test/api/v1/vestigingsprofielen/000037178598"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "https://api.kvk.nl/test/api/v2/zoeken?kvknummer=68750110&amp;pagina=1&amp;resultatenperpagina=10"
    }
  ]
}
</code></pre></div>

HATEOAS - Resultaten - Output standaard

<h2 id="hateoas">HATEOAS</h2><p>Met de Zoeken API zoek je naar bedrijfsgegevens, vestigings-gegevens en/of rechtspersonen. De Basisprofiel en Vestigingsprofiel API’s zijn gelinkt aan de Zoeken API. Ze bevatten zoekresultaten URL’s naar de gerelateerde Basisprofiel resource en Vestigingsprofiel resources. Dit is binnen REST ook wel bekend als HATEOAS. We hebben de HAL standard gebruikt om HATEOAS te implementeren.</p><h2 id="results">Resultaten</h2><ul><li data-list-item-id="ef280bcac654635f54f3d24d5a7d7997c">Registraties die niet meer actief zijn worden standaard niet getoond in de resultaten.</li><li data-list-item-id="efd89fe9a9b26b9e3b4214795d9a66f0a">Er wordt geen GIO-melding getoond. Een GIO-melding (Gegevens in Onderzoek) geeft aan dat bepaalde gegevens in onderzoek zijn. De informatie die je bekijkt is daardoor mogelijk niet correct. Voor interne processen, waarbij rechtszekerheid van belang is, kun je andere KVK-producten gebruiken. Zoals het <a target="_blank" rel="noopener noreferrer" href="https://www.kvk.nl/producten-bestellen/uittreksel-handelsregister-kamer-van-koophandel/">uittreksel Handelsregister</a>.</li><li data-list-item-id="efd795aa7ef4fff050c20a2d69919a84c">Zoeken werkt op gehele tekst d-matching. Bijvoorbeeld: ‘koophand’ geeft nul resultaten en ‘koophandel’ ongeveer 1000.</li><li data-list-item-id="e81c9c2f0e062f543c618b4bd7a5bc5fe">De KVK API geeft maximaal 100 resultaten per pagina weer (default = 10 resultaten per pagina).</li><li data-list-item-id="edf8f1818399e1de0e3b9a3500b6f0eeb">Er is geen garantie dat de resultaten op volgorde worden weergegeven (vestigingen en/of rechtspersonen). Maar er is wel een voorkeur voor sortering hoofdvestiging, nevenvestigingen, rechtspersoon.</li></ul><h2 id="output-standard">Output standaard</h2><p>Een http GET-request is de enige toegestane http methode voor de API. Voor de output maken we gebruik van standaard JSON object (JavaScript Object Notation). Dit zorgt voor generieke resultaten. Bij elke JSON output worden ook een aantal metadata elementen geleverd (pagina, aantal, totaal, volgende en vorige).</p><p>We gebruiken de specificaties die zijn voorgeschreven door JSON.org. Er zijn echter 2 specifieke kenmerken met betrekking tot de KVK API JSON output: registratiedatum en geodata.</p><h3 id="registration-date">Registratiedatum</h3><p>De datum geregistreerd in het Handelsregister kan nullen bevatten als de datum onbekend is. Als de volledige datum bekend is dan is het formaat: YYYYMMDD (year/month/day). Alleen numerieke waarden zijn toegestaan (inclusief 0 voor onbekende delen van de datum).</p><ul><li data-list-item-id="eb824fc40dfcce7288dbc74bc287a4930">complete datum: 20150622</li><li data-list-item-id="e23704a98179dcead8581f941d62a0423">dag onbekend: 20150600</li><li data-list-item-id="e456e5e5bf5f6356eba57cfe73b07b550">maand onbekend: 20150000</li><li data-list-item-id="e1ca6ac429ec93a8bc0ad6fac0a59153c">datum onbekend: 00000000</li></ul><h3 id="geo-data">Geodata</h3><p>Geodata zijn geografische gegevens die gebruikt worden om de locatie van adressen en gebouwen aan te geven. Met behulp van de BAG ID’s (addresseerbaarObjectId en nummerAanduidingId) kan in de BAG (Basisregistratie Adressen en Gebouwen) gezocht worden naar onder andere oppervlakte en gebruiksdoel.</p><p>Geodata worden opgehaald door de extra parameter “?geoData=true” op te nemen in de aanroep bij vestigingsprofielen. Standaard staat deze parameter op false.</p><h3>Voorbeeld van geodata als onderdeel van een adres:</h3><div><pre><code class="language-json">{
  "adressen":[
    {
      "type":"bezoekadres",
      "indicatieAfgeschermd":"Nee",
      "volledigAdres":"Watermolenlaan 1 3447GT Woerden",
      "straatnaam":"Watermolenlaan",
      "huisnummer":1,
      "postcode":"3447GT",
      "plaats":"Woerden",
      "land":"Nederland",
      "geoData":{
        "addresseerbaarObjectId":"0632010000010090",
        "nummerAanduidingId":"0632200000010090",
        "gpsLatitude":52.08151653230184,
        "gpsLongitude":4.890048011859921,
        "rijksdriehoekX":120921.45,
        "rijksdriehoekY":454921.47,
        "rijksdriehoekZ":0
      }
    }
  ]
}</code></pre></div>

Statuscodes

<h2 id="status-codes">Statuscodes</h2><p>Als er een foutboodschap en/of error handling plaatsvindt, dan worden normale http-statuscodes en -boodschappen gehanteerd. Foutboodschappen en error handling gebruiken de volgende niet uitputtende lijst van foutcodes:</p><ul><li data-list-item-id="ed660c0df2daef054d3cf02e8e9f6c1f7">400 - Bad request</li><li data-list-item-id="e631ccdd791fd81e4ce23efd3ec529cc7">401 - Not authenticated</li><li data-list-item-id="e1cd21efcf89befeb8d8dea03f8aa76fe">404 - Not found</li><li data-list-item-id="e844ea71f2a3458d5c5f27afd01bd59f5">500 - Internal server error</li></ul><h3>IPD codes</h3><figure class="table"><table><thead><tr><th>Code</th><th>Omschrijving</th><th>Http status</th></tr></thead><tbody><tr><td>IPD0001</td><td>Het gevraagde product {0} bestaat niet.</td><td>404</td></tr><tr><td>IPD0004</td><td>Het KvK nummer {0} is niet valide.</td><td>400</td></tr><tr><td>IPD0005</td><td>Op basis van het KVK-nummer {0} kan het product niet worden geleverd.</td><td>404</td></tr><tr><td>IPD0006</td><td>Het vestigingsnummer {0} is niet valide.</td><td>400</td></tr><tr><td>IPD0007</td><td>Op basis van het vestigingsnummer {0} kan het product niet worden geleverd.</td><td>404</td></tr><tr><td>IPD0010</td><td>Het RSI-nummer {0} is niet valide.</td><td>400</td></tr><tr><td>IPD1002</td><td>De gegevens zijn tijdelijk niet leverbaar omdat deze in behandeling zijn. Probeer het later nog eens.</td><td>404</td></tr><tr><td>IPD1003</td><td>De gegevens zijn tijdelijk niet leverbaar. Probeer het over 5 minuten nog een keer.&nbsp;</td><td>404</td></tr><tr><td>IPD1998</td><td>Algemene invoer parameter fout.</td><td>400</td></tr><tr><td>IPD1999</td><td>De volgende opgegeven parameter(s) is(zijn) ongeldig: {0}</td><td>400</td></tr><tr><td>IPD5200</td><td>Er zijn geen gegevens gevonden die voldoen aan de opgegeven zoekparameters.</td><td>404</td></tr><tr><td>IPD5203</td><td>Het opgegeven type is niet valide.</td><td>404</td></tr><tr><td>IPD9999</td><td>Algemene technische fout.</td><td>500</td></tr></tbody></table></figure>

Legal entities output

<h2 id="legal-entities-output">Rechtsvormen output</h2><p>In onderstaande PDF staat de informatie die een zoekopdracht naar rechtsvormen oplevert.</p><ul><li data-list-item-id="ed75782f21a301691a4901b9a7c244906"><a target="_blank" rel="noopener noreferrer" href="https://developers.kvk.nl/cms/api/uploads/Lijst_output_rechtsvormen.pdf">Lijst output (uitgebreide) rechtsvormen</a></li></ul><h2 id="foreign-legal-forms">Buitenlandse rechtsvormen</h2><p>In onderstaande PDF staan waarden die bij het attribuut ‘omschrijvingRechtsvorm’ kunnen voorkomen.</p><ul><li data-list-item-id="e74470050740b96dfc42c79ae37510f4b"><a target="_blank" rel="noopener noreferrer" href="https://developers.kvk.nl/cms/api/uploads/Overzicht_buitenlandse_rechtsvormen_uit_Gegevenscatalogus.pdf">Overzicht buitenlandse rechtsvormen uit gegevenscatalogus</a></li></ul><h2 id="country-codes">Landcodes</h2><p>In onderstaande PDF staan de mogelijke waarden voor een land, aangeduid volgens de BRP-landentabel (ook wel bekend als Tabel 34).</p><ul><li data-list-item-id="ea7420fbc3557685176f76b1775e27aac"><a target="_blank" rel="noopener noreferrer" href="https://developers.kvk.nl/cms/api/uploads/Landen_tabel_extract_uit_GC_Enumeratie.pdf">Landen tabel extract uit GC Enumeratie</a></li></ul>

Here you will find all the necessary documentation to use the KVK Handelsregister APIs.

Overview API Documentation

Hier vind je alle benodigde documentatie om de KVK Handelsregister API te bevragen.

Overzicht API documentatie

<p>Met de Swagger UI kun je de KVK API's testen. De widget gebruikt een set fictieve data. Hieronder vind je enkele KVK-nummers (en bijbehorende rechtsvorm) die in de dataset zijn opgenomen. Ook bieden we de OpenAPI specificatie in YAML.</p>

<figure class="table"><table><thead><tr><th>KVK-nummer</th><th>Rechtsvorm</th></tr></thead><tbody><tr><td>69599084</td><td>Eenmanszaak</td></tr><tr><td>90004973</td><td>Foutmelding</td></tr><tr><td>68727720</td><td>NV</td></tr><tr><td>90004760</td><td>NV</td></tr><tr><td>68750110</td><td>BV</td></tr><tr><td>90001354</td><td>BV</td></tr><tr><td>69599068</td><td>Stichting</td></tr><tr><td>90000102</td><td>Stichting</td></tr><tr><td>90006623</td><td>Stichting</td></tr><tr><td>69599076</td><td>VoF</td></tr></tbody></table></figure>

<figure class="table"><table><thead><tr><th>KVK-nummer</th><th>Rechtsvorm</th></tr></thead><tbody><tr><td>90005414</td><td>VoF</td></tr><tr><td>96354429</td><td>Coöperatie (inactief)</td></tr><tr><td>90002520</td><td>Kerkgenootschap</td></tr><tr><td>90002490</td><td>Onderlinge Waarborg Maatschappij</td></tr><tr><td>90002903</td><td>Foutmelding</td></tr><tr><td>90000749</td><td>Vereniging van Eigenaars</td></tr><tr><td>90001745</td><td>Maatschap</td></tr><tr><td>90003942</td><td>Commanditaire Vennootschap</td></tr><tr><td>55505201</td><td>Overige Privaatrechtelijke Rechtspersoon</td></tr></tbody></table></figure>

naamgeving-widget.yaml

Swagger - Naamgeving

Check out our swagger tool to immediately see the possible request and response parameters of the KVK Naamgeving API.

Gebruik onze swagger tool om de input en output te zien van de KVK Naamgeving API, of download de OpenApi Specificatie [YAML]

Test de API's

Release notes

Swagger - Naamgeving

Testdata

OpenAPI Specificatie

KVK-nummer	Rechtsvorm
69599084	Eenmanszaak
90004973	Foutmelding
68727720	NV
90004760	NV
68750110	BV
90001354	BV
69599068	Stichting
90000102	Stichting
90006623	Stichting
69599076	VoF

KVK-nummer	Rechtsvorm
90005414	VoF
96354429	Coöperatie (inactief)
90002520	Kerkgenootschap
90002490	Onderlinge Waarborg Maatschappij
90002903	Foutmelding
90000749	Vereniging van Eigenaars
90001745	Maatschap
90003942	Commanditaire Vennootschap
55505201	Overige Privaatrechtelijke Rechtspersoon