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 :

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.

GET /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
string
Numéro KVK à 8 chiffres (paramètre de chemin)
vat
boolean
Passez à true pour récupérer le KVK Basisprofiel : numéro de TVA (validé via VIES), effectifs, dénomination statutaire, date d'immatriculation officielle et descriptions SBI officielles. Coûte 12 jetons au lieu de 2. Le numéro de TVA est dérivé du RSIN : il n'est donc renvoyé que pour les personnes morales comme une BV ou une NV ; une entreprise individuelle ou une société de personnes n'a pas de RSIN au registre et obtient vat: null. Les autres champs sont renvoyés pour toutes les formes juridiques.

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"
  }
}
GET /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
string
Numéro de TVA, par exemple NL123456789B01 (paramètre de chemin)

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
}
GET /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
string
Numéro d'entreprise, 10 chiffres avec une paire de chiffres de contrôle valide, dans n'importe quelle notation (paramètre de chemin)
lang
string
Langue des libellés, comme la forme juridique et les descriptions d'activités : nl, fr ou de. Par défaut, l'en-tête Accept-Language, puis nl. en est accepté et traité en néerlandais.

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"
  }
}
POST /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
string[]
Tableau de numéros d'entreprise, dans n'importe quelle notation (corps de la requête, 25 maximum)
lang
string
nl, fr ou de (corps de la requête, par défaut : Accept-Language, puis nl)

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
}
GET /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
string
Numéro de TVA belge, par exemple BE0821015819 (paramètre de chemin)

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"
}
GET /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.

Sujet
Détails
Format du numéro
Les numéros d'entreprise comptent 10 chiffres et une paire de chiffres de contrôle. 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.
Champs
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.
Langue
Le paramètre 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.
Fraîcheur
Une réponse d'entreprise peut dater d'une semaine au maximum, une réponse de recherche d'une heure. 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 (stale pour une recherche). Consultez source.cachedAt pour connaître l'âge de la donnée.
Statut de la TVA
L'objet 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.
Jetons
1 jeton par recherche d'entreprise, par recherche par nom et par entreprise dans un lot. La validation de TVA coûte 1 jeton.
Erreurs
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 :

Formule
Limite
En-têtes
free
10 req/min
X-RateLimit-Limit, X-RateLimit-Remaining
starter
60 req/min
X-RateLimit-Limit, X-RateLimit-Remaining
pro
300 req/min
X-RateLimit-Limit, X-RateLimit-Remaining
business
1 000 req/min
X-RateLimit-Limit, X-RateLimit-Remaining

Coût en jetons

Appel
Coût
Remarques
Recherche simple
1 jeton
Raison sociale, adresse, statut
Recherche enrichie
2 jetons
Noms commerciaux, adresse, forme juridique, codes SBI et établissements (?enrich=true)
Enrichie via KVK Basisprofiel
12 jetons
Ajoute les effectifs, la dénomination statutaire, la date d'immatriculation et les descriptions SBI officielles, ainsi que le numéro de TVA des personnes morales (?enrich=true&vat=true)
Recherche par nom
1 jeton
Par requête de recherche
Établissements
5 jetons
Tous les établissements d'une entreprise
Belgique : recherche, recherche par nom, élément de lot
1 jeton
Par recherche, par requête de recherche par nom, par entreprise dans un lot
Belgique : validation de TVA
1 jeton
Contrôle de validation VIES
Vérification
Gratuit
Existence et statut actif

En cas de dépassement de la limite, l'API renvoie 429 Too Many Requests avec un en-tête Retry-After.