Overview API Documentation

A KVK API functions as an interface between your software applications and the KVK Trade Register. It allows the two to communicate with each other. An API key gives you access to information in the Trade Register.

Why use the KVK API?

  • Autofill: You can directly retrieve current information from the Trade Register within your own CRM system, website or financial package. The data will be automatically supplemented (prefill).
  • Validity check: You can check business customers on Chamber of Commerce number, address details, SBI and working people

Available APIs

KVK Handelsregister Zoeken

With this API you can search for companies in the Business Register. You search by KVK-number, RSIN, location number, trade name, street name and city. The result is a list of companies. A maximum of 1000 results will be shown (default 10 per page but this can be adjusted to 100). After this you can request further details using the Basisprofiel or Vestigingsprofiel API.

KVK Handelsregister Basisprofiel

With this API you request basic data from companies in the Business Register, like the details of the main establishment, the activities associated with this KVK number, and a link to an overview of all branches, the branch list. You search by KVK number.

KVK Handelsregister Vestigingsprofiel

With this API you can request specific location data of companies in the Business Register such as general data, activities of this branch specifically, visiting and postal address and BAG (basic registration of addresses and buildings) and GPS coordinates. You search by branch number.

KVK Handelsregister Naamgeving

With this API you request name data of companies from the Business Register. For example, statutory name, trade names and non-commercial name. You select by KVK number.

Using the APIs

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

  • KVK number and branch number (vestigingsnummer).
  • KVK number and RSIN number (RSIN: Rechtspersonen en Samenwerkingsverbanden Informatienummer - Legal Entities and Partnerships Identification Number)
  • KVK number and type (branch, main branch, and/or legal entity)

For free format search, the other input parameters (e.g. trade name, street name, etc.) can be used.

Data model

The Zoeken API contains 2 separate entities that differ in their property "type":

  • Branch
  • Legal entity

Example of legal entity in 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"
        }
      }
    }
  ]
}

Example of type branch in 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

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 HATEAOS. We used the HAL standard for these APIs to implement HATEOAS.

Results

  • Registrations that are no longer active are not shown in the results by default.
  • Search works on whole-text d-matching. For example, "koophand" has zero results while "koophandel" has about 1,000 results.
  • The KVK Zoeken API displays a maximum of 100 results per page (default = 10 results per page).
  • 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.

Output standard

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:

Registratiedatum

The date registered in the Trade 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).
For example:

  • complete date: 20150622
  • day unknown: 20150600
  • month unknown: 20150000
  • date unknown : 00000000

Geo-data

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

Example of GEO-data as part of an address:

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

Status codes

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:

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

IPD codes

CodeDescriptionHttp status
IPD0001The requested product {0} does not exist.404
IPD0004The KVK number {0} is not valid400
IPD0005The product cannot be delivered based on the KVK number {0}.404
IPD0006The vestigingsnummer (branch number) {0} is not valid.400
IPD0007The product cannot be delivered based on vestigingsnummer {0}.404
IPD0010The RSIN number {0} is not valid.400
IPD1002The data is temporarily unavailable because it is being processed. Please try again later.404
IPD1998General input parameter error.400
IPD1999The following specified parameter(s) is(are) invalid: {0}400
IPD5200No data was found that matches the specified search parameters.404
IPD5203The specified type is not valid.404
IPD9999General technical error.500

The PDF below contains the information that a search for legal forms yields. Information is in Dutch.

The PDF below contains values that can occur with the attribute 'omschrijvingRechtsvorm'. Information is in Dutch.

Country codes

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.