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

Enriched lookup

5 tokens

Full details + VAT validation (?enrich=true)

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

GET /v1/lookup/{kvkNumber} 1 token (basic) / 5 tokens (enriched)

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.

Parameters

Name

Type

Description

kvkNumber required

string

8-digit KVK number (path parameter)

enrich

boolean

Set to true for full details with VAT validation (costs 5 tokens instead of 1)

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,
    "validatedAt": "2026-03-15T12:00:00Z"
  },
  "source": {
    "kvk": "opendata+zoeken",
    "vies": "validated",
    "cachedAt": "2026-03-15T12:00:00Z"
  }
}

GET /v1/search 1 token

Company Search

Search for companies by name or trade name. Returns paginated results with basic company information. For search-as-you-type use cases, prefer the /v1/autocomplete endpoint.

Parameters

Name

Type

Description

q required

string

Search query (min 2 characters)

page

integer

Page number (default: 1)

pageSize

integer

Results per page (1-50, default: 10)

Request

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

Response

{
  "results": [
    {
      "kvkNumber": "12345678",
      "name": "Acme B.V.",
      "city": "Amsterdam",
      "isActive": true
    }
  ],
  "total": 42,
  "page": 1,
  "pageSize": 10
}

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 or 5 tokens per item

Batch Lookup

Look up multiple companies in a single request. Accepts an array of KVK numbers. Each item costs 1 token for basic data, or 5 tokens if enrich is set to true. Max 100 items per request.

Parameters

Name

Type

Description

kvkNumbers required

string[]

Array of 8-digit KVK numbers (request body)

enrich

boolean

Set to true for enriched results (5 tokens per item)

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.

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

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

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.