link

# KvK Search and Profile API

The KvK (opens new window) Search and Profile API is a lookup service where you can search in the Dutch company register and retrieve organisational data from a specific organisation. This lookup service is useful if you, for example, want to check a company against AML regulations (Anti Money Laundering).

The KvK Search and Profile API more specifically enables you to search, for example, on company name and get back the company KvK number, including a short profile with for example information about the company type, number of employees, address etc.

Signicat has implemented the following two APIs from the KvK company register:

This document describes how to interact with these two APIs.

As an alternative to this API, Signicat offers the iDIN/KvK API, which allows you to check if an individual person (after being authenticated via iDIN) fulfils a certain role within a specific organisation.

# Use case

You can use the KvK lookup service in many scenarios. For example, a credit card issuer can check a company's legitimacy before issuing credit cards to their employees. The merchant can then build in the lookup service to automatically search for the company name and number while typing (search) and the application form is automatically filled in with the organisation data (profile).

# How to integrate with Signicat

Integration with the KvK service is done with OIDC. See Accessing Signicat REST Services for more information.

# How to use the KvK Search and Profile API

# Location

The KvK Search and Profile API is available at:

Environment Base URL
Beta https://beta.signicat.com
Pre-production https://preprod.signicat.com
Pre-production EU https://eu01.preprod.signicat.com
Production https://id.signicat.com
Production EU https://eu01.signicat.com

Endpoints for Search and Profile:

Path Method Scope Content type Input Output Description
kvk/search POST client.kvk application/json KvkSearchRequest KvkResponse Endpoint for searching the KvK registry
kvk/profile POST client.kvk application/json KvkProfileRequest KvkResponse Endpoint for doing a KvK registry profile lookup

# HTTP headers

You must set the Accept HTTP header (receiving content type) to application/json:

Name Value
Accept application/json

# Search request

You can perform a search for a business registered in KvK using various parameters. Here are some common rules:

  • You must specify at least one parameter.
  • All parameter values are formatted as strings.
  • Results are paginated, which means that a maximum of 10 results are returned per request.
  • To get the next set of requests, run the same query again with the startPage parameter added.
  • Parameters are sent as a JSON object.
  • The order of parameters does not matter.
Parameter Description
kvkNumber Identifies the company registration number in the Dutch company register. Consists of 8 digits.
branchNumber (Vestigingsnummer) Identifies the branch number of the company. Consists of 12 digits.
rsin Identification number for legal entities and partnerships. Consists of digits only.
street Street of an address.
houseNumber House number of an address.
postalCode Postal code or ZIP code, for example, 1000AA.
city City or town name.
tradeName The name of the company or a branch.
includeFormerTradeNames Search through expired trade names and expired registered names and/or include these in the results. Values: True or false (default).
includeInactiveRegistrations Search through inactive dossiers/deregistered companies. Values: True or false (default). Note: The history of inactive companies goes back to 1 January 2012.
mainBranch Search includes main branches. Values: True (default) or false.
branch Search includes branches. Values: True (default) or false.
legalPerson Search includes legal persons. Values: True (default) or false.
startPage A number indicating which page to fetch for pagination. Default = 1, showing the first 10 results.
site Defines the search collection for the query.
context The user can optionally add context to identify their result later on.
q Free-format text search.

# Example search request

{
    "q": "bv",
    "includeInactiveRegistrations": "true",
    "includeFormerTradenames": "true"
}

# Profile request

You can perform a profile request for a company registered in KvK using various parameters.

Here are some common rules:

  • You must specify at least one parameter.
  • All parameter values are formatted as strings.
  • Results are paginated, which means that a maximum of 10 results are returned per request.
  • To get the next set of requests, run the same query again with the startPage parameter added.
  • Parameters are sent as a JSON object.
  • The order of parameters does not matter.

# Possible parameters for profile

Parameter Description
kvkNumber Identifies the company registration number in the Dutch company register. Consists of 8 digits.
branchNumber (Vestigingsnummer) Identifies the branch number of the company. Consists of 12 digits.
rsin Identification number for legal entities and partnerships. Consists of digits only.
includeInactiveRegistrations Search through inactive dossiers/deregistered companies. Values: True or false (default). Note: The history of inactive companies goes back to 1 January 2012.
restrictToMainBranch Search is restricted to the main branches. Values: True or false (default).
startPage A number indicating which page to fetch for pagination. Default = 1, showing the first 10 results.
site Defines the search collection for the query.
context The user can optionally add a context to identify their result later on.
q Free-format text search.

# Example profile request

{
    "q": "nv",
    "restrictToMainBranch": "true"
}

# Understanding the results (responses)

Responses are in JSON format. Signicat forwards the response we get from KvK in its entirety. Empty search request results will return an empty response from KvK. Signicat also forwards those. Empty profile request results will return a 404 error (see Error code 404).

# Valid responses

# Example search response

{
    "apiVersion": "2.0",
    "meta": {},
    "data": {
        "itemsPerPage": 10,
        "startPage": 1,
        "totalItems": 5,
        "items": [
            {
                "kvkNumber": "90001354",
                "rsin": "992760562",
                "tradeNames": {
                    "shortBusinessName": "Grand Kontex B.V.",
                    "currentStatutoryNames": [
                        "Grand Kontex B.V."
                    ]
                },
                "hasEntryInBusinessRegister": true,
                "hasNonMailingIndication": false,
                "isLegalPerson": true,
                "isBranch": false,
                "isMainBranch": false
            },
            {
                "kvkNumber": "90001354",
                "branchNumber": "990000541921",
                "rsin": "992760562",
                "tradeNames": {
                    "businessName": "Grand Kontex B.V.",
                    "shortBusinessName": "Grand Kontex B.V.",
                    "currentTradeNames": [
                        "Grand Kontex B.V."
                    ],
                    "currentStatutoryNames": [
                        "Grand Kontex B.V."
                    ]
                },
                "hasEntryInBusinessRegister": true,
                "hasNonMailingIndication": false,
                "isLegalPerson": false,
                "isBranch": true,
                "isMainBranch": true,
                "addresses": [
                    {
                        "type": "vestigingsadres",
                        "street": "Keizerhof",
                        "houseNumber": "68",
                        "houseNumberAddition": "",
                        "postalCode": "3135CT",
                        "city": "Vlaardingen",
                        "country": "Nederland"
                    }
                ],
                "websites": [
                    "www.kvk.nl"
                ]
            },
            {
                "kvkNumber": "68750110",
                "branchNumber": "000037178598",
                "rsin": "857587973",
                "tradeNames": {
                    "businessName": "Test BV Donald",
                    "shortBusinessName": "Test BV Donald",
                    "currentTradeNames": [
                        "Test BV Donald"
                    ],
                    "currentStatutoryNames": [
                        "Test BV Donald"
                    ]
                },
                "hasEntryInBusinessRegister": true,
                "hasNonMailingIndication": true,
                "isLegalPerson": false,
                "isBranch": true,
                "isMainBranch": true,
                "addresses": [
                    {
                        "type": "vestigingsadres",
                        "street": "Hizzaarderlaan",
                        "houseNumber": "3",
                        "houseNumberAddition": "",
                        "postalCode": "8823SJ",
                        "city": "Lollum",
                        "country": "Nederland"
                    }
                ]
            },
            {
                "kvkNumber": "68750110",
                "rsin": "857587973",
                "tradeNames": {
                    "shortBusinessName": "Test BV Donald",
                    "currentStatutoryNames": [
                        "Test BV Donald"
                    ]
                },
                "hasEntryInBusinessRegister": true,
                "hasNonMailingIndication": true,
                "isLegalPerson": true,
                "isBranch": false,
                "isMainBranch": false
            },
            {
                "kvkNumber": "68750110",
                "branchNumber": "000037178601",
                "rsin": "857587973",
                "tradeNames": {
                    "businessName": "Test BV Donald Nevenvestiging",
                    "shortBusinessName": "Test BV Donald",
                    "currentTradeNames": [
                        "Test BV Donald Nevenvestiging"
                    ],
                    "currentStatutoryNames": [
                        "Test BV Donald"
                    ]
                },
                "hasEntryInBusinessRegister": true,
                "hasNonMailingIndication": true,
                "isLegalPerson": false,
                "isBranch": true,
                "isMainBranch": false,
                "addresses": [
                    {
                        "type": "vestigingsadres",
                        "street": "Brinkerinckbaan",
                        "houseNumber": "3",
                        "houseNumberAddition": "",
                        "postalCode": "7431BX",
                        "city": "Diepenveen",
                        "country": "Nederland"
                    }
                ]
            }
        ]
    }
}

# Example profile response

{
    "apiVersion": "2.0",
    "meta": {},
    "data": {
        "itemsPerPage": 1,
        "startPage": 1,
        "totalItems": 1,
        "items": [
            {
                "kvkNumber": "68727720",
                "branchNumber": "000037143557",
                "rsin": "857567433",
                "tradeNames": {
                    "businessName": "Test NV Katrien",
                    "shortBusinessName": "Test NV Katrien",
                    "currentTradeNames": [
                        "Test NV Katrien"
                    ],
                    "currentStatutoryNames": [
                        "Test NV Katrien"
                    ]
                },
                "legalForm": "Naamloze vennootschap met gewone structuur",
                "businessActivities": [
                    {
                        "sbiCode": "93127",
                        "sbiCodeDescription": "Auto- en motorsport",
                        "isMainSbi": true
                    }
                ],
                "hasEntryInBusinessRegister": true,
                "hasCommercialActivities": true,
                "hasNonMailingIndication": true,
                "isLegalPerson": false,
                "isBranch": true,
                "isMainBranch": true,
                "employees": 1,
                "foundationDate": "20160516",
                "registrationDate": "20170516",
                "addresses": [
                    {
                        "type": "vestigingsadres",
                        "bagId": "0047010000304580",
                        "street": "Rietdekkershof",
                        "houseNumber": "8",
                        "houseNumberAddition": "",
                        "postalCode": "9646AS",
                        "city": "Veendam",
                        "country": "Nederland",
                        "gpsLatitude": 53.11299973488547,
                        "gpsLongitude": 6.870000594767678,
                        "rijksdriehoekX": 254283.411,
                        "rijksdriehoekY": 570600.516,
                        "rijksdriehoekZ": 0.0
                    },
                    {
                        "type": "correspondentieadres",
                        "bagId": "",
                        "street": "Postbus",
                        "houseNumber": "200",
                        "houseNumberAddition": "",
                        "postalCode": "1000AE",
                        "city": "Rommeldam",
                        "country": "Nederland"
                    }
                ]
            }
        ]
    }
}

# Error code 400

This is an invalid request, possibly due to unexpected or missing parameters. It can also be due to a malformed JSON.

# Example JSON for unexpected parameter

{
    "instance": "<ENVIRONMENT>/kvk/profile",
    "method": "POST",
    "status": 400,
    "type": "base:json-mismatched-input-problem",
    "title": "JSON mismatched input problem",
    "detail": "Could not bind '$.spanishInquisition'. Only known properties at this level are [q, restrictToMainBranch, rsin, includeInactiveRegistrations, kvkNumber, branchNumber, context, startPage, site]."
}

# Example JSON response for no parameters

{
    "instance": "<ENVIRONMENT>/kvk/profile",
    "method": "POST",
    "status": 400,
    "type": "base:client-problem",
    "title": "No query parameters specified"
}

# Error code 404

The application could not find data, usually due to a malformed URL. KvK also returns 404 when no results were found in a profile query. Search queries just return an empty result. In the latter case, the response from KvK is returned in its entirety just like a normal response.

# Example JSON response for malformed URL

{
    "instance": "<ENVIRONMENT>/kvk/profilez",
    "method": "POST",
    "status": 404,
    "type": "base:client-problem",
    "title": "404 Not Found"
}

# Example JSON response for empty profile query result

{
    "apiVersion": "2.0",
    "meta": {},
    "error": {
        "code": 404,
        "message": "NotFound",
        "reason": "No companies found for the given query."
    }
}

# Error code 500

An unexpected error occurred on the server-side.

Last updated: 12/10/2022 12:16 UTC