Overzicht API documentatie

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.

Wat zijn de voordelen van een KVK API?

  • Automatisch aanvullen: haal direct actuele informatie op uit het Handelsregister binnen je eigen CRM-systeem, website of financiële pakket. De gegevens worden automatisch aangevuld (prefill).
  • Controleren: controleer zakelijke klanten op KVK-nummer, adresgegevens, SBI en werkzame personen.

Welke API's zijn er?

KVK Handelsregister Zoeken

Zoek bedrijven op in het Handelsregister met bijvoorbeeld het KVK-nummer, RSIN of vestigingsnummer. Het resultaat is een lijst van bedrijven. Er worden maximaal 1000 resultaten getoond (standaard 10 per pagina maar dit is aan te passen naar 100). Vervolgens vraag je met een andere API zoals Basisprofiel of Vestigingsprofiel gegevens op.

KVK Handelsregister Basisprofiel

Vraag basisgegevens van bedrijven op in het Handelsregister. Je zoekt op KVK-nummer of geodata. De uitkomst is een lijst met basisgegevens van de hoofdvestiging, eigenaar of vestigingen. Bijvoorbeeld KVK-nummer, adressen of handelsnamen.

KVK Handelsregister Vestigingsprofiel

Vraag specifieke vestigingsgegevens van bedrijven op in het Handelsregister. Je zoekt op vestigingsnummer. De uitkomst is een lijst met specifieke gegevens van de hoofdvestiging of eigenaar zoals KVK-nummer, statutaire naam, RSIN etc.

KVK Handelsregister Naamgeving

Vraag naamgegevens op van bedrijven uit het Handelsregister. Je zoekt op KVK-nummer en de uitkomst is een lijst met naamgegevens zoals statutaire naam, handelsnamen en niet-commerciële naam.

Hoe gebruik je een KVK API?

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:

  • KVK-nummer en vestigingsnummer
  • KVK-nummer en RSIN
  • KVK-nummer en type (hoofdvestiging, nevenvestiging en/of rechtspersoon)

Gebruik voor free format zoeken de overige inputparameters (bijvoorbeeld handelsnaam of straatnaam).

Datamodel

De Zoeken API heeft 2 aparte entiteiten die verschillen in de property "type".

  • Vestiging
  • Rechtspersoon

Voorbeeld rechtspersoon met de Zoeken API:

{
  "pagina": 1,
  "aantal": 10,
  "totaal": 1,
  "resultaten": [
    {
      "kvkNummer": "69599068",
      "handelsnaam": "Test Stichting Bolderbast",
      "adresType": "bezoekadres",
      "straatnaam": "Oosterwal",
      "plaats": "Lochem",
      "type": "rechtspersoon",
      "_links": {
        "basisprofiel": {
          "href": "https://api.kvk.nl/test/api/v1/basisprofielen/69599068"
        }
      }
    }
  ]
}

Voorbeeld vestiging met de Zoeken API:

{
  "pagina":1,
  "aantal":10,
  "totaal":1,
  "resultaten":[
    {
      "kvkNummer":"68750110",
      "vestigingsnummer":"000037178598",
      "handelsnaam":"Test BV Donald",
      "adresType":"bezoekadres",
      "straatnaam":"Hizzaarderlaan",
      "plaats":"Lollum",
      "type":"hoofdvestiging",
      "_links":{
        "basisprofiel":{
          "href":"https://api.kvk.nl/test/api/v1/basisprofielen/68750110"
        },
        "vestigingsprofiel":{
          "href":"https://api.kvk.nl/test/api/v1/vestigingsprofielen/000037178598"
        }
      }
    }
  ]
} 

HATEOAS

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 HATEAOS. We hebben de HAL standard gebruikt om HATEOAS te implementeren.

Resultaten

  • Registraties die niet meer actief zijn worden standaard niet getoond in de resultaten.
  • Zoeken werkt op gehele tekst d-matching. Bijvoorbeeld: ‘koophand’ geeft nul resultaten en ‘koophandel’ ongeveer 1000.
  • De KVK API geeft maximaal 100 resultaten per pagina weer (default = 10 resultaten per pagina).
  • 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.

Output standard

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).

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.

Registratiedatum

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).

  • complete datum: 20150622
  • dag onbekend: 20150600
  • maand onbekend: 20150000
  • datum onbekend: 00000000

Geodata

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.

Geodata worden opgehaald door de extra parameter “?geoData=true” op te nemen in de aanroep bij vestigingsprofielen. Standaard staat deze parameter op false.

Voorbeeld van geodata als onderdeel van een adres:

{
  "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
      }
    }
  ]
}

Statuscodes

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:

  • 400 - Bad request
  • 401 - Not authenticated
  • 404 - Not found
  • 500 - Internal server error

IPD codes

CodeOmschrijvingHttp status
IPD0001Het gevraagde product {0} bestaat niet.404
IPD0004Het KvK nummer {0} is niet valide.400
IPD0005Op basis van het KVK-nummer {0} kan het product niet worden geleverd.404
IPD0006Het vestigingsnummer {0} is niet valide.400
IPD0007Op basis van het vestigingsnummer {0} kan het product niet worden geleverd.404
IPD0010Het RSI-nummer {0} is niet valide.400
IPD1002De gegevens zijn tijdelijk niet leverbaar omdat deze in behandeling zijn. Probeer het later nog eens.404
IPD1998Algemene invoer parameter fout.400
IPD1999De volgende opgegeven parameter(s) is(zijn) ongeldig: {0}400
IPD5200Er zijn geen gegevens gevonden die voldoen aan de opgegeven zoekparameters.404
IPD5203Het opgegeven type is niet valide.404
IPD9999Algemene technische fout.500

In onderstaande PDF staat de informatie die een zoekopdracht naar rechtsvormen oplevert.

In onderstaande PDF staan waarden die bij het attribuut ‘omschrijvingRechtsvorm’ kunnen voorkomen.

Landcodes

In onderstaande PDF staan de mogelijke waarden voor een land, aangeduid volgens de BRP-landentabel (ook wel bekend als Tabel 34).