docs-Documentation

Overzicht

Overview

Snelstart

Quickstart

Test de API's

Testing the APIs

Release notes

Certificaten

Certificates

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>A KVK API functions as an interface between your software applications and the KVK Business Register. It allows the two to communicate with each other. An API key gives you access to information in the Business Register.</p>

Why use the KVK API?

<h2>Why use the KVK API?</h2><ul><li><strong>Autofill</strong>: You can directly retrieve current information from the Business Register within your own CRM system, website or financial package. The data will be automatically supplemented (prefill).</li><li><strong>Validity check</strong>: You can check business customers on KVK number, address details, SBI and working people</li></ul><h2 id="available-apis">Available APIs</h2><h3>KVK Handelsregister Zoeken</h3><p>You can use the Zoeken API to retrieve the KVK number of a registration.</p><h3>KVK Handelsregister Basisprofiel</h3><p>Look up basic information of registrations with the KVK number. For example, social activity, details of owner/main location, and a list of locations.</p><h3>KVK Handelsregister Vestigingsprofiel</h3><p>Look up specific information of registrations with the location number. For example basic information, business activities and physical and postal address.</p><h3>KVK Handelsregister Naamgeving</h3><p>Use the KVK number to retrieve trade names from a registration. For example statutory name, trade names and non-commercial name.</p>

Using the APIs

<h2 id="using-the-apis">Using the APIs</h2><p>Only the KVK Zoeken API delivers multiple results, the other APIs all return a single result. If a search with Basisprofiel, Vestigingsprofiel or Naamgeving results in multiple registrations, the first result will be shown. Therefore, we recommend using a combination of fields to make your search in the Zoeken API as specific as possible. For instance you could combine</p><ul><li>KVK number and branch number (vestigingsnummer).</li><li>KVK number and RSIN number (RSIN: Rechtspersonen en Samenwerkingsverbanden Informatienummer - Legal Entities and Partnerships Identification Number)</li><li>KVK number and type (branch, main branch, and/or legal entity)</li></ul><p>For free format search, the other input parameters (e.g. trade name, street name, etc.) can be used.</p>

Data model

<h2 id="data-model">Data model</h2><p>The Zoeken API contains 2 separate entities that differ in their property "type":</p><ul><li>Branch</li><li>Legal entity</li></ul><h3>Example of legal entity in Zoeken API</h3><div class="jsx-3943413509"><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>Example of type branch in Zoeken API</h3><div class="jsx-3943413509"><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 - Results - Output standard

<h2 id="hateoas">HATEOAS</h2><p>The Zoeken API offers the possibility to search for company data, location data and/or legal entities. The Basispofiel and Vestigingsprofiel APIs are linked to the Zoeken API. Search results contain URLs to the related Basisprofiel en Vestigingsprofiel resources. Within REST this is also known as HATEOAS. We used the HAL standard for these APIs to implement HATEOAS.</p><h2 id="results">Results</h2><ul><li data-list-item-id="ef471861c6e0e703875310f2abebac64a">Registrations that are no longer active are not shown in the results by default.</li><li data-list-item-id="e06ee2a605eb6e8c37b495427153c54aa">No GIO message is displayed. A GIO notification (Gegevens in Onderzoek) indicates that certain data is under investigation. The information you view may therefore not be correct. You can use other KVK products for internal processes where legal certainty is important. Such as the <a target="_blank" rel="noopener noreferrer" href="https://www.kvk.nl/en/ordering-products/kvk-business-register-extract/">Business Register extract</a>.</li><li data-list-item-id="eb2720b627362cb3fc8e28c2b36962d84">Search works on whole-text d-matching. For example, "koophand" has zero results while "koophandel" has about 1,000 results.</li><li data-list-item-id="e4ed11b10e94fc1aab48669ede13c2961">The KVK Zoeken API displays a maximum of 100 results per page (default = 10 results per page).</li><li data-list-item-id="e38b15486ab8be07ca4a20b3e4c0dbc60">The API does not guarantee that the results are in order (branches or legal entities). But there is a preference for sorting by headquarters, branches, legal entity.</li></ul><h2 id="output-standard">Output standard</h2><p>An http GET-request is the only allowed http request. The KVK APIs use the standard JSON object (JavaScript Object Notation) as output. This facilitates generic results for the API output. It also contains a number of metadata elements that are included with every JSON output (page, count, total, next and previous). We use the specifications prescribed by JSON.org. However, there are 2 very specific features related to the KVK API JSON output:</p><h3 id="registration-date">Registratiedatum</h3><p>The date registered in the Business Register can contain zeros as the date is unknown. If the full date is known then the format is: YYYYMMDD (year/month/day). Only numeric values are allowed (including 0 for unknown parts of the date).<br>For example:</p><ul><li data-list-item-id="ec7bce8dd20326a64999fa65efff3c754">complete date: 20150622</li><li data-list-item-id="eb626f5d506a10e9ae14766113f34ab9a">day unknown: 20150600</li><li data-list-item-id="ee00346bb7c0811c3379cfcd470102f13">month unknown: 20150000</li><li data-list-item-id="ee9cb3810946e874d21f1f6b9c549f25d">date unknown : 00000000</li></ul><h3 id="geo-data">Geo-data</h3><p>GEO data is geographic data used to determine the location of addresses and buildings to indicate. Using the BAG IDs (addressableObjectId and numberIndicationId) can be entered in the BAG (Basic Registration Addresses and Buildings) are searched for, among other things, surface area and purpose of use.<br>Geo-data is retrieved by including an extra parameter “?geoData=true” in the call to location profiles. By default, this parameter is set to false. The coordinates are only provided if they are known (for PO boxes for example, this will be empty).</p><p>Example of GEO-data as part of an address:</p><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>

Statuscodes

<h2 id="status-codes">Status codes</h2><p>If there is an error message and/or error handling occurs, normal http status codes and messages used. Error messages and error handling use the following non-exhaustive list of error codes:</p><ul><li>400 - Bad request</li><li>401 - Not authenticated</li><li>404 - Not found</li><li>500 - Internal server error</li></ul><h3>IPD codes</h3><figure class="table"><table><thead><tr><th>Code</th><th>Description</th><th>Http status</th></tr></thead><tbody><tr><td><span>IPD0001</span></td><td><span>The requested product {0} does not exist.</span></td><td><span>404</span></td></tr><tr><td><span>IPD0004</span></td><td><span>The KVK number {0} is not valid</span></td><td><span>400</span></td></tr><tr><td><span>IPD0005</span></td><td><span>The product cannot be delivered based on the KVK number {0}.</span></td><td><span>404</span></td></tr><tr><td><span>IPD0006</span></td><td><span>The vestigingsnummer (branch number) {0} is not valid.</span></td><td><span>400</span></td></tr><tr><td><span>IPD0007</span></td><td><span>The product cannot be delivered based on vestigingsnummer {0}.</span></td><td><span>404</span></td></tr><tr><td><span>IPD0010</span></td><td><span>The RSIN number {0} is not valid.</span></td><td><span>400</span></td></tr><tr><td><span>IPD1002</span></td><td><span>The data is temporarily unavailable because it is being processed. Please try again later.</span></td><td><span>404</span></td></tr><tr><td>IPD1003</td><td><span>The data is temporarily unavailable. Please try again in 5 minutes.&nbsp;</span></td><td>404</td></tr><tr><td><span>IPD1998</span></td><td><span>General input parameter error.</span></td><td><span>400</span></td></tr><tr><td><span>IPD1999</span></td><td><span>The following specified parameter(s) is(are) invalid: {0}</span></td><td><span>400</span></td></tr><tr><td><span>IPD5200</span></td><td><span>No data was found that matches the specified search parameters.</span></td><td><span>404</span></td></tr><tr><td><span>IPD5203</span></td><td><span>The specified type is not valid.</span></td><td><span>404</span></td></tr><tr><td><span>IPD9999</span></td><td><span>General technical error.</span></td><td><span>500</span></td></tr></tbody></table></figure>

Legal entities output

<h2 id="legal-entities-output">Legal entities output</h2><p>The PDF below contains the information that a search for legal forms yields. Information is in Dutch.</p><ul><li><a href="https://developers.kvk.nl/cms/api/uploads/Lijst_output_rechtsvormen.pdf">Extensive list of output legal forms</a></li></ul><h2 id="foreign-legal-forms">Foreign legal forms</h2><p>The PDF below contains values that can occur with the attribute 'omschrijvingRechtsvorm'. Information is in Dutch.</p><ul><li><a href="https://developers.kvk.nl/cms/api/uploads/Overzicht_buitenlandse_rechtsvormen_uit_Gegevenscatalogus.pdf">Overview of foreign legal forms from data catalog</a></li></ul><h2 id="country-codes">Country codes</h2><p>The PDF below contains the possible values for a country, indicated according to the BRP country table (also known as Table 34). Information is in Dutch.</p><ul><li><a href="https://developers.kvk.nl/cms/api/uploads/Landen_tabel_extract_uit_GC_Enumeratie.pdf">Country table extract from GC Enumeration</a></li></ul>

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

Overzicht API documentatie

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

Overview API Documentation

<p>With the Swagger UI you can test the KVK API's. The widget uses a set fictitious data. Below you will find the KVK numbers (and corresponding legal business form) included in the dataset. We also offer the OpenAPI specification in YAML.</p>

<figure class="table"><table><thead><tr><th>KVK number</th><th>Legal form</th></tr></thead><tbody><tr><td>000038509504</td><td>Eenmanszaak</td></tr><tr><td>000038509520</td><td>Eenmanszaak</td></tr><tr><td>000037178598</td><td>BV</td></tr><tr><td>000037178601</td><td>BV</td></tr><tr><td>990000541921</td><td>BV (Afgeschermd bezoekadres)</td></tr><tr><td>000037143557</td><td>NV</td></tr><tr><td>990064773193</td><td>Stichting (geoData)</td></tr><tr><td>990064773207</td><td>Stichting (geoData)</td></tr><tr><td>000038509474</td><td>VoF</td></tr><tr><td>000038509490</td><td>VoF</td></tr></tbody></table></figure>

<figure class="table"><table><thead><tr><th>KVK number</th><th>Legal form</th></tr></thead><tbody><tr><td>990000216645</td><td>VoF</td></tr><tr><td>990000821206</td><td>VoF</td></tr><tr><td>990001987781</td><td>Coöperatie (inactive)</td></tr><tr><td>990000246858</td><td>Onderlinge Waarborg Maatschappij</td></tr><tr><td>990000637800</td><td>Maatschap</td></tr><tr><td>990000008288</td><td>Commanditaire Vennootschap</td></tr><tr><td>990000246530</td><td>Commanditaire Vennootschap</td></tr><tr><td>990000768218</td><td>Commanditaire Vennootschap</td></tr><tr><td>990000852070</td><td>Commanditaire Vennootschap</td></tr></tbody></table></figure>

api_vestigingsprofiel_widget.yaml

Swagger - Vestigingsprofiel

Gebruik de swagger tool om de KVK Vestigingsprofiel API te testen. Download hier ook de OpenApi Specification!

Use the swagger tool to test the KVK Vestigingsprofiel API. Also download the OpenApi Specification here!

Testing the APIs

Release notes

Swagger - Vestigingsprofiel

Testdata

OpenAPI Specification

KVK number	Legal form
000038509504	Eenmanszaak
000038509520	Eenmanszaak
000037178598	BV
000037178601	BV
990000541921	BV (Afgeschermd bezoekadres)
000037143557	NV
990064773193	Stichting (geoData)
990064773207	Stichting (geoData)
000038509474	VoF
000038509490	VoF

KVK number	Legal form
990000216645	VoF
990000821206	VoF
990001987781	Coöperatie (inactive)
990000246858	Onderlinge Waarborg Maatschappij
990000637800	Maatschap
990000008288	Commanditaire Vennootschap
990000246530	Commanditaire Vennootschap
990000768218	Commanditaire Vennootschap
990000852070	Commanditaire Vennootschap