# 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.
# Possible parameters for search
| 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.