API Reference

Base URL https://api.kvkbase.nl/v1

Authentication

All endpoints (except /v1/health) require an API key. Two methods are supported:

Recommended

Bearer Token

Authorization: Bearer YOUR_API_KEY

Query Parameter

?apikey=YOUR_API_KEY

Get your API key from the Dashboard. Keys are scoped to your account tier and token allowance.

Token System

Every API call costs tokens. Your plan determines your monthly token allowance. Different endpoints and options cost different amounts:

Operation
Cost
Notes
Basic lookup
1 token
Company name, address, status
Verrijkte lookup
2 tokens
Handelsnamen, adres, rechtsvorm, SBI-codes en vestigingen (?enrich=true)
Verrijkt via KVK Basisprofiel
12 tokens
Voegt aantal medewerkers, statutaire naam, inschrijfdatum en officiële SBI-omschrijvingen toe, plus het btw-nummer bij rechtspersonen (?enrich=true&vat=true)
Search
1 token
Per search request
Autocomplete
1 token
Per autocomplete request
Batch lookup
1-5 / item
Depends on enrich setting
Branches
5 tokens
All branches for a company
VAT validation
1 token
VIES validation check
Health check
Free
No authentication required

Het btw-nummer wordt afgeleid uit het RSIN, en alleen een rechtspersoon zoals een BV of NV heeft er een in het Handelsregister staan. Bij een eenmanszaak of VOF komt vat terug als null: die hebben wel een btw-id, maar dat wordt willekeurig toegekend en staat in geen enkel openbaar register. De overige velden van het Basisprofiel komen bij elke rechtsvorm terug. Heb je het nummer al, dan controleert /v1/validate/vat/{nummer} het voor 1 token bij VIES.

GET /v1/lookup/{kvkNumber} 1 token (basis) / 2 tokens (verrijkt) / 12 tokens (met btw-nummer)

Company Lookup

Look up company information by KVK number. Returns basic company data by default. Add ?enrich=true for full details including activities, legal form, and VIES-validated VAT number. The vat object carries a status of validated, stale, malformed or unvalidated, so a VIES outage never reaches you as a false negative. See the Error Codes page for what each one means.

Parameters

Name
Type
Description
kvkNumber required
string
8-digit KVK number (path parameter)
enrich
boolean
Zet op true voor handelsnamen, volledig adres, rechtsvorm, SBI-codes en vestigingen (2 tokens in plaats van 1)
vat
boolean
Zet op true om het KVK Basisprofiel op te halen: btw-nummer (gevalideerd via VIES), aantal medewerkers, statutaire naam, formele inschrijfdatum en de officiële SBI-omschrijvingen. Kost 12 tokens in plaats van 2. Het btw-nummer wordt afgeleid uit het RSIN, dus het komt alleen terug bij rechtspersonen zoals een BV of NV; een eenmanszaak of VOF heeft geen RSIN in het Handelsregister en krijgt vat: null. De overige velden komen bij elke rechtsvorm terug.

Request

curl "https://api.kvkbase.nl/v1/lookup/12345678?enrich=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch(
  "https://api.kvkbase.nl/v1/lookup/12345678?enrich=true",
  {
    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",
    params={"enrich": "true"},
    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?enrich=true");
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?enrich=true", 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."

Response

{
  "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/autocomplete 1 token

Autocomplete

Lightweight search designed for search-as-you-type dropdowns. Returns minimal data (KVK number, name, city) with fast response times. Ideal for forms and UI components.

Parameters

Name
Type
Description
q required
string
Search query (min 2 characters)
limit
integer
Max results (1-20, default: 8)

Request

curl "https://api.kvkbase.nl/v1/autocomplete?q=acme&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch(
  "https://api.kvkbase.nl/v1/autocomplete?q=acme&limit=5",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const { results } = await response.json();
// Use results to populate a dropdown
response = requests.get(
    "https://api.kvkbase.nl/v1/autocomplete",
    params={"q": "acme", "limit": 5},
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
results = response.json()["results"]
$url = "https://api.kvkbase.nl/v1/autocomplete?" . http_build_query([
    "q" => "acme", "limit" => 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/autocomplete?q=acme&limit=5", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req)

Response

{
  "results": [
    {
      "kvkNumber": "12345678",
      "name": "Acme B.V.",
      "city": "Amsterdam"
    },
    {
      "kvkNumber": "87654321",
      "name": "Acme Trading B.V.",
      "city": "Rotterdam"
    }
  ]
}
POST /v1/lookup/batch 1, 2 of 12 tokens per bedrijf

Batch Lookup

Zoek meerdere bedrijven op in één request. Accepteert een array van KVK-nummers. Per bedrijf kost dit 1 token voor de basisgegevens, 2 tokens met enrich, of 12 tokens met enrich en vat. Maximaal 25 KVK-nummers per request.

Parameters

Name
Type
Description
kvkNumbers required
string[]
Array of 8-digit KVK numbers (request body)
enrich
boolean
Zet op true voor verrijkte gegevens per bedrijf (2 tokens per bedrijf)
vat
boolean
Zet op true om het KVK Basisprofiel op te halen per bedrijf: btw-nummer bij rechtspersonen, plus medewerkers, statutaire naam en inschrijfdatum (12 tokens per bedrijf)

Request

curl -X POST "https://api.kvkbase.nl/v1/lookup/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kvkNumbers": ["12345678", "87654321"],
    "enrich": false
  }'
const response = await fetch(
  "https://api.kvkbase.nl/v1/lookup/batch",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      kvkNumbers: ["12345678", "87654321"],
      enrich: false,
    }),
  }
);
const { results, failed, tokensUsed } = await response.json();
response = requests.post(
    "https://api.kvkbase.nl/v1/lookup/batch",
    json={
        "kvkNumbers": ["12345678", "87654321"],
        "enrich": False,
    },
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()
for company in data["results"]:
    print(company["name"])
$ch = curl_init("https://api.kvkbase.nl/v1/lookup/batch");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_KEY",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "kvkNumbers" => ["12345678", "87654321"],
    "enrich" => false,
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch));
body, _ := json.Marshal(map[string]interface{}{
    "kvkNumbers": []string{"12345678", "87654321"},
    "enrich":     false,
})
req, _ := http.NewRequest("POST",
    "https://api.kvkbase.nl/v1/lookup/batch",
    bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)

Response

{
  "results": [
    {
      "kvkNumber": "12345678",
      "name": "Acme B.V.",
      "address": {
        "city": "Amsterdam",
        "postalCode": "1015 AA"
      },
      "isActive": true
    },
    {
      "kvkNumber": "87654321",
      "name": "Example Corp B.V.",
      "address": {
        "city": "Rotterdam",
        "postalCode": "3011 AA"
      },
      "isActive": true
    }
  ],
  "failed": [],
  "tokensUsed": 2
}
GET /v1/lookup/{kvkNumber}/branches 5 tokens

Company Branches

Get all branches (vestigingen) for a company. Returns a list of branch locations with their own addresses and details.

Parameters

Name
Type
Description
kvkNumber required
string
8-digit KVK number (path parameter)

Request

curl "https://api.kvkbase.nl/v1/lookup/12345678/branches" \
  -H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch(
  "https://api.kvkbase.nl/v1/lookup/12345678/branches",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const { branches } = await response.json();
branches.forEach(b => console.log(b.name, b.address.city));
response = requests.get(
    "https://api.kvkbase.nl/v1/lookup/12345678/branches",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()
for branch in data["branches"]:
    print(branch["name"], branch["address"]["city"])
$ch = curl_init("https://api.kvkbase.nl/v1/lookup/12345678/branches");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch));
foreach ($data->branches as $branch) {
    echo $branch->name . "\n";
}
req, _ := http.NewRequest("GET",
    "https://api.kvkbase.nl/v1/lookup/12345678/branches", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req)

Response

{
  "kvkNumber": "12345678",
  "name": "Acme B.V.",
  "branches": [
    {
      "branchNumber": "000012345678",
      "name": "Acme B.V. - Hoofdvestiging",
      "isMain": true,
      "address": {
        "street": "Herengracht",
        "houseNumber": "100",
        "postalCode": "1015 AA",
        "city": "Amsterdam"
      },
      "isActive": true
    },
    {
      "branchNumber": "000087654321",
      "name": "Acme B.V. - Filiaal Rotterdam",
      "isMain": false,
      "address": {
        "street": "Coolsingel",
        "houseNumber": "50",
        "postalCode": "3011 AD",
        "city": "Rotterdam"
      },
      "isActive": true
    }
  ]
}
GET /v1/validate/vat/{vatNumber} 1 token

VAT Validation

Validate a Dutch or EU VAT number against the VIES system. Returns validation status and registered company details. When a member state service is down, status tells you whether you are looking at a live verdict (validated), a dated one we obtained earlier (stale, with ageSeconds), or a number the Dutch checksum rejects outright (malformed). A 502 UPSTREAM_ERROR is reserved for when we have none of those. checksumValid is the Dutch elfproef: it means well formed, never valid.

Parameters

Name
Type
Description
vatNumber required
string
VAT number, e.g. NL123456789B01 (path parameter)

Request

curl "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)

Response

{
  "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/health Free

Health Check

Check API and upstream service status. No authentication required.

Request

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")

Response

{
  "status": "ok",
  "services": {
    "kvk": "up",
    "vies": "up"
  },
  "timestamp": "2026-03-15T12:00:00Z"
}

Rate Limits

Rate limits are applied per API key based on your plan tier. Limits are measured in tokens per month:

Tier
Monthly Tokens
Rate Limit
free
50 tokens
10 req/min
starter
1,000 tokens
60 req/min
pro
5,000 tokens
300 req/min
business
50,000 tokens
1,000 req/min

When rate limited, the API returns 429 Too Many Requests with a Retry-After header. Rate limit headers are included in every response:

Header
Description
X-RateLimit-Limit
Max requests per minute for your plan
X-RateLimit-Remaining
Requests remaining in current window
X-RateLimit-Reset
Unix timestamp when window resets
X-Tokens-Remaining
Tokens remaining this month
Retry-After
Seconds to wait (only on 429)

Errors

All errors return a consistent JSON format:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "No company found with KVK number 99999999"
  }
}

See the Error Codes page for a complete reference with HTTP status codes and handling examples.