About the KvK Search and Profile API

The KvK Search and Profile API is a lookup service where you can search in the Dutch company register and retrieve organizational data from a specific organization. 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 DIN/KvK API, which enables you to check if an individual person (after being authenticated via iDIN) fulfils a certain role within a specific organization.

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 organization data (profile).

How to integrate with Signicat

Integration with the KvK service is done via the same API as Signicat’s ID methods. Authorization is done via OIDC, see Get started with authentication for more information. Through the single point of integration, you will get access to Signicat’s wide portfolio of integrated ID methods and other services like identity paper verification and lookups.

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
Preproduction https://preprod.signicat.com
Production https://id.signicat.com

Endpoints for Search and Profile:

Path Method Scope Content type Input Output Description
kvk/lite/search POST client.kvklite application/json KvkSearchRequest KvkResponse Endpoint for searching the KvK registry
kvk/lite/profile POST client.kvklite 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

Profile request

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

Here are some common rules:

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 his 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/lite/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/lite/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/lite/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.