Référence de l'API
URL de base https://api.kvkbase.nl/v1
Authentification
Tous les points d'accès (sauf /v1/health) nécessitent une clé API. Deux méthodes sont prises en charge :
Jeton Bearer
Authorization: Bearer YOUR_API_KEY Paramètre d'URL
?apikey=YOUR_API_KEY Obtenez votre clé API depuis le tableau de bord. Les clés héritent de l'offre de votre compte et de ses limites de débit.
/v1/lookup/{kvkNumber} Recherche d'entreprise
Recherchez les informations détaillées d'une entreprise à partir de son numéro KVK. Renvoie en un seul appel la raison sociale, l'adresse, la forme juridique, les activités et le numéro de TVA validé par VIES. L'objet vat porte un statut validated, stale, malformed ou unvalidated : une panne de VIES ne vous parvient donc jamais comme un faux négatif. Consultez la page Codes d'erreur pour la signification de chacun.
Paramètres
kvkNumber obligatoire vat Requête
curl -X GET "https://api.kvkbase.nl/v1/lookup/12345678" \
-H "Authorization: Bearer YOUR_API_KEY" const response = await fetch(
"https://api.kvkbase.nl/v1/lookup/12345678",
{
headers: {
Authorization: "Bearer YOUR_API_KEY",
},
}
);
const company = await response.json();
console.log(company.name); // "Acme B.V." import requests
response = requests.get(
"https://api.kvkbase.nl/v1/lookup/12345678",
headers={"Authorization": "Bearer YOUR_API_KEY"}
)
company = response.json()
print(company["name"]) # "Acme B.V." $ch = curl_init("https://api.kvkbase.nl/v1/lookup/12345678");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch));
echo $response->name; // "Acme B.V." req, _ := http.NewRequest("GET",
"https://api.kvkbase.nl/v1/lookup/12345678", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var company map[string]interface{}
json.NewDecoder(resp.Body).Decode(&company)
fmt.Println(company["name"]) // "Acme B.V." require "net/http"
require "json"
uri = URI("https://api.kvkbase.nl/v1/lookup/12345678")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
http.request(req)
}
company = JSON.parse(res.body)
puts company["name"] # "Acme B.V." Réponse
{
"kvkNumber": "12345678",
"name": "Acme B.V.",
"tradingNames": ["Acme", "Acme Trading"],
"legalForm": "BV",
"address": {
"street": "Herengracht",
"houseNumber": "100",
"postalCode": "1015 AA",
"city": "Amsterdam",
"country": "NL"
},
"isActive": true,
"registrationDate": "2020-01-15",
"activities": [
{ "sbiCode": "6201", "description": "Ontwikkelen en uitgeven van software", "isMain": true }
],
"vat": {
"number": "NL123456789B01",
"valid": true,
"status": "validated",
"validatedAt": "2026-03-15T12:00:00Z",
"checksumValid": true
},
"source": {
"kvk": "opendata+zoeken",
"vies": "validated",
"cachedAt": "2026-03-15T12:00:00Z"
}
} /v1/search Recherche d'entreprises
Recherchez des entreprises par raison sociale ou nom commercial. Renvoie des résultats paginés avec les informations de base de l'entreprise.
Paramètres
q obligatoire page pageSize Requête
curl -X GET "https://api.kvkbase.nl/v1/search?q=acme&pageSize=5" \
-H "Authorization: Bearer YOUR_API_KEY" const params = new URLSearchParams({ q: "acme", pageSize: "5" });
const response = await fetch(
`https://api.kvkbase.nl/v1/search?${params}`,
{ headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const { results, total } = await response.json(); response = requests.get(
"https://api.kvkbase.nl/v1/search",
params={"q": "acme", "pageSize": 5},
headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()
for company in data["results"]:
print(company["name"]) $url = "https://api.kvkbase.nl/v1/search?" . http_build_query([
"q" => "acme", "pageSize" => 5
]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch)); req, _ := http.NewRequest("GET",
"https://api.kvkbase.nl/v1/search?q=acme&pageSize=5", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req) uri = URI("https://api.kvkbase.nl/v1/search")
uri.query = URI.encode_www_form(q: "acme", pageSize: 5)
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY" Réponse
{
"results": [
{
"kvkNumber": "12345678",
"name": "Acme B.V.",
"city": "Amsterdam",
"isActive": true
}
],
"total": 42,
"page": 1,
"pageSize": 10
} /v1/validate/vat/{vatNumber} Validation de TVA
Validez un numéro de TVA néerlandais ou européen auprès du système VIES. Renvoie le statut de validation et les données de l'entreprise enregistrée. Lorsque le service d'un État membre est indisponible, status indique s'il s'agit d'un verdict en direct (validated), d'un verdict plus ancien obtenu auparavant (stale, avec ageSeconds) ou d'un numéro que le contrôle de somme néerlandais rejette d'emblée (malformed). Une erreur 502 UPSTREAM_ERROR n'est renvoyée que lorsque nous n'avons aucun de ces éléments. checksumValid correspond à l'elfproef néerlandais : il signifie bien formé, jamais valide.
Paramètres
vatNumber obligatoire Requête
curl -X GET "https://api.kvkbase.nl/v1/validate/vat/NL123456789B01" \
-H "Authorization: Bearer YOUR_API_KEY" const response = await fetch(
"https://api.kvkbase.nl/v1/validate/vat/NL123456789B01",
{ headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const { valid, name } = await response.json(); response = requests.get(
"https://api.kvkbase.nl/v1/validate/vat/NL123456789B01",
headers={"Authorization": "Bearer YOUR_API_KEY"}
)
result = response.json()
print(f"Valid: {result['valid']}") $ch = curl_init(
"https://api.kvkbase.nl/v1/validate/vat/NL123456789B01"
);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch)); req, _ := http.NewRequest("GET",
"https://api.kvkbase.nl/v1/validate/vat/NL123456789B01", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req) uri = URI("https://api.kvkbase.nl/v1/validate/vat/NL123456789B01")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY" Réponse
{
"vatNumber": "NL123456789B01",
"valid": true,
"name": "Acme B.V.",
"address": "Herengracht 100, 1015 AA Amsterdam",
"validatedAt": "2026-03-15T12:00:00Z",
"status": "validated",
"checksumValid": true
} /v1/be/lookup/{cbeNumber} Belgique : recherche d'entreprise
Recherchez une entreprise belge par son numéro d'entreprise. Toutes les notations usuelles fonctionnent : 0821.015.819, BE0821015819 ou 821015819. La même recherche est aussi accessible via GET /v1/lookup/{number}. Renvoie en un seul appel la dénomination, les noms commerciaux, la forme juridique, l'adresse, le statut, les activités NACE (dans le champ sbiCode, avec la version dans naceVersion), les établissements et le statut de la TVA. L'objet vat fonctionne comme son équivalent néerlandais : validated est un verdict de VIES ou de son cache, stale est un verdict plus ancien datant d'une indisponibilité de VIES, unvalidated signifie que nous n'avons aucun verdict et valid vaut null. Un verdict que nous n'avons pas n'est jamais présenté comme false. Les réponses peuvent dater d'une semaine au maximum. Lorsque nous ne pouvons pas actualiser une fiche, par exemple parce que notre quota de données du jour est épuisé, nous servons la copie stockée et mettons source.stale à true. Coûte 1 jeton.
Paramètres
cbeNumber obligatoire lang Requête
curl "https://api.kvkbase.nl/v1/be/lookup/0821.015.819?lang=nl" \
-H "Authorization: Bearer YOUR_API_KEY" const response = await fetch(
"https://api.kvkbase.nl/v1/be/lookup/BE0821015819",
{ headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const company = await response.json();
console.log(company.name, company.vat?.status); // "INSPACE" "validated" Réponse
{
"country": "BE",
"cbeNumber": "0821015819",
"cbeNumberFormatted": "0821.015.819",
"name": "INSPACE",
"tradingNames": [],
"legalForm": "Besloten vennootschap",
"legalFormCode": "610",
"legalFormShort": "BV",
"entityType": "legal_person",
"address": {
"street": "Rue des Deux Chaussees",
"houseNumber": "25",
"postalCode": "1160",
"city": "Auderghem",
"country": "BE"
},
"isActive": true,
"juridicalSituation": "Normale toestand",
"juridicalSituationCode": "000",
"registrationDate": "2009-12-01",
"activities": [
{ "sbiCode": "43990", "description": "Overige gespecialiseerde bouwactiviteiten", "isMain": true },
{ "sbiCode": "64200", "description": "Holdings", "isMain": false }
],
"naceVersion": "Nace2025",
"establishments": [
{
"establishmentNumber": "2183353402",
"startDate": "2009-12-18",
"address": { "street": "Rue des Deux Chaussees", "houseNumber": "25", "postalCode": "1160", "city": "Auderghem", "country": "BE" }
}
],
"vat": {
"number": "BE0821015819",
"valid": true,
"status": "validated",
"validatedAt": "2026-11-09T09:30:00Z",
"checksumValid": true
},
"enriched": false,
"source": {
"cbe": "register",
"vies": "live",
"cachedAt": "2026-11-09T09:30:00Z"
}
} /v1/be/search Belgique : recherche d'entreprises
Recherchez des entreprises belges par nom, code postal ou les deux. Renvoie au maximum 25 entreprises par requête. capped vaut true lorsque la limite est atteinte : affinez alors la requête avec un code postal. Page et pageSize ne font que découper cette liste. Les résultats comportent la forme juridique, le statut et la localité ; utilisez la recherche par numéro pour la fiche complète. Les réponses de recherche peuvent dater d'une heure au maximum. Lorsque notre quota de données du jour est épuisé, nous servons une copie stockée de la même requête et mettons stale à true. Coûte 1 jeton par requête.
Paramètres
q postalCode page pageSize lang Requête
curl "https://api.kvkbase.nl/v1/be/search?q=colruyt&postalCode=1500" \
-H "Authorization: Bearer YOUR_API_KEY" const params = new URLSearchParams({ q: "colruyt", postalCode: "1500" });
const response = await fetch(
`https://api.kvkbase.nl/v1/be/search?${params}`,
{ headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const { results, total, capped } = await response.json(); Réponse
{
"results": [
{
"cbeNumber": "0400378485",
"cbeNumberFormatted": "0400.378.485",
"name": "Colruyt Group",
"entityType": "legal_person",
"legalForm": "Naamloze vennootschap",
"legalFormShort": "NV",
"postalCode": "1500",
"city": "Halle",
"country": "BE",
"isActive": true
}
],
"total": 1,
"page": 1,
"pageSize": 10,
"capped": false
} /v1/be/lookup/batch Belgique : recherche par lot
Recherchez jusqu'à 25 entreprises belges en une seule requête. Coûte 1 jeton par numéro d'entreprise, débité d'avance. La requête échoue avec 400 INVALID_CBE_NUMBER si un numéro est invalide. Pour chaque entreprise, le résultat est soit un succès avec les mêmes données qu'une recherche unitaire, soit un objet d'erreur : une entreprise introuvable ne fait donc pas échouer le lot. Un numéro présent deux fois n'est recherché qu'une fois.
Paramètres
cbeNumbers obligatoire lang Requête
curl -X POST "https://api.kvkbase.nl/v1/be/lookup/batch" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"cbeNumbers": ["0821.015.819", "BE0417497106"]}' const response = await fetch(
"https://api.kvkbase.nl/v1/be/lookup/batch",
{
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
cbeNumbers: ["0821.015.819", "BE0417497106"],
}),
}
);
const { results, count, tokensUsed } = await response.json(); Réponse
{
"results": {
"0821015819": { "success": true, "data": { "country": "BE", "cbeNumber": "0821015819", "name": "INSPACE", "...": "same fields as a single lookup" } },
"0417497106": { "success": false, "error": { "error": { "code": "NOT_FOUND", "message": "Company with enterprise number 0417497106 not found." } } }
},
"count": 2,
"tokensUsed": 2
} /v1/be/validate/vat/{vatNumber} Belgique : validation de TVA
Validez un numéro de TVA belge (BE suivi du numéro d'entreprise à 10 chiffres ; un numéro à 9 chiffres est également accepté) auprès de VIES. Le chemin avec le préfixe BE, /v1/validate/vat/BE0821015819, fonctionne de la même façon. Un numéro qui échoue au contrôle des chiffres belges est signalé comme malformed sans appeler VIES. Les valeurs de statut et le champ checksumValid ont la même signification que pour les numéros de TVA néerlandais : validated, stale, malformed, et 502 UPSTREAM_ERROR lorsque nous n'avons rien du tout.
Paramètres
vatNumber obligatoire Requête
curl "https://api.kvkbase.nl/v1/be/validate/vat/BE0821015819" \
-H "Authorization: Bearer YOUR_API_KEY" const response = await fetch(
"https://api.kvkbase.nl/v1/be/validate/vat/BE0821015819",
{ headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const { valid, status } = await response.json(); Réponse
{
"vatNumber": "BE0821015819",
"valid": true,
"validatedAt": "2026-11-09T09:30:00Z",
"status": "validated",
"checksumValid": true,
"country": "BE"
} /v1/health État du service
Vérifiez l'état de l'API et des services en amont. Aucune authentification requise.
Requête
curl https://api.kvkbase.nl/v1/health const response = await fetch("https://api.kvkbase.nl/v1/health");
const health = await response.json();
console.log(health.status); // "ok" response = requests.get("https://api.kvkbase.nl/v1/health")
print(response.json()["status"]) # "ok" $health = json_decode(
file_get_contents("https://api.kvkbase.nl/v1/health")
); resp, _ := http.Get("https://api.kvkbase.nl/v1/health") res = Net::HTTP.get(URI("https://api.kvkbase.nl/v1/health")) Réponse
{
"status": "ok",
"services": {
"kvk": "up",
"vies": "up"
},
"timestamp": "2026-03-15T12:00:00Z"
} Notes sur la Belgique
Les points d'accès belges ci-dessus renvoient le même type de données que les points d'accès néerlandais, avec les différences suivantes.
0821.015.819, BE0821015819 et 821015819 désignent la même entreprise. cbeNumber n'a pas de séparateurs, cbeNumberFormatted utilise des points. Un numéro invalide reçoit une réponse 400 INVALID_CBE_NUMBER avant tout débit de jetons.country vaut toujours BE. legalForm est le libellé dans la langue demandée, legalFormCode le code du registre, legalFormShort l'abréviation (BV, NV, etc.). entityType vaut legal_person ou natural_person. isActive vaut true, false ou null lorsque l'information est inconnue. activities contient les codes NACE dans sbiCode ; naceVersion indique la version de la NACE utilisée par les codes.lang accepte nl, fr ou de et détermine la langue de la forme juridique, de la situation juridique et des descriptions d'activités. en est accepté et servi en néerlandais.source.stale à true (stale pour une recherche). Consultez source.cachedAt pour connaître l'âge de la donnée.vat a la même sémantique que pour les entreprises néerlandaises : validated, stale, malformed ou unvalidated, avec valid: null lorsque nous n'avons aucun verdict. Une panne de VIES n'apparaît jamais comme un faux négatif.INVALID_CBE_NUMBER (400) pour un numéro mal formé ou une paire de chiffres de contrôle erronée. UPSTREAM_BUDGET (503, avec Retry-After) lorsque notre quota de données du jour est épuisé et que la fiche n'est pas encore stockée : réessayez après le nombre de secondes indiqué dans l'en-tête. NOT_FOUND (404) pour un numéro inconnu. Consultez la page Codes d'erreur.Erreurs
Toutes les erreurs renvoient un format JSON cohérent :
{
"error": {
"code": "NOT_FOUND",
"message": "No company found with KVK number 99999999"
}
} Consultez la page Codes d'erreur pour une référence complète avec les codes de statut HTTP.
Limites de débit
Les limites de débit s'appliquent par clé API selon votre offre :
freestarterprobusinessCoût en jetons
?enrich=true)?enrich=true&vat=true)En cas de dépassement de la limite, l'API renvoie 429 Too Many Requests avec un en-tête Retry-After.