API

Eén bedrijf per call, op zijn KVK-nummer of zijn domein. Terug als JSON.

Een bedrijf ophalen

Stuur een KVK-nummer en je krijgt het bedrijf terug: wat het doet en gebruikt, als vaste velden.

Veldnamen zijn Engels, in snake_case. De uitleg en de foutberichten zijn Nederlands.

website is de hoofdsite van het bedrijf, websites zijn de domeinen die we bij het bedrijf kennen. Een lijst is een array, ook met één waarde erin.

GET /v1/companies/00000002

{  "kvk_number": "00000002",  "name": "Voorbeeld B.V.",  "legal_form": "bv",  "active": true,  "vat_number": "NL000000002B01",  "address": {    "street": "Voorbeeldstraat",    "house_number": "1",    "postcode": "3511AA",    "city": "Utrecht",    "country": "NL",    "latitude": 52.0907,    "longitude": 5.1214  },  "building": {    "uses": [      "kantoorfunctie"    ],    "floor_area": 180,    "construction_year": 1931  },  "website": "voorbeeld.nl",  "websites": [    "voorbeeld.nl",    "voorbeeldbv.nl"  ],  "languages": [    "nl",    "en"  ],  "services": [    "Advies",    "Onderhoud"  ],  "trust_marks": [],  "rating": null,  "apps": [],  "webshop": false,  "webshop_platform": null,  "payment_providers": [],  "payment_methods": [],  "shipping_countries": [],  "shipping_area": null,  "phone": "+31301234567",  "whatsapp": null,  "email": "[email protected]",  "social_profiles": [    {      "platform": "linkedin",      "url": "https://www.linkedin.com/company/voorbeeld"    }  ],  "chat": [],  "booking": false,  "booking_tools": [],  "opening_hours": [    {      "day": "monday",      "opens": "09:00",      "closes": "17:00"    },    {      "day": "tuesday",      "opens": "09:00",      "closes": "17:00"    },    {      "day": "wednesday",      "opens": "09:00",      "closes": "17:00"    },    {      "day": "thursday",      "opens": "09:00",      "closes": "17:00"    },    {      "day": "friday",      "opens": "09:00",      "closes": "17:00"    }  ],  "open_vacancies": 2,  "vacancies": [    {      "title": "Adviseur",      "location": "Utrecht",      "employment_type": "FULL_TIME",      "url": "https://voorbeeld.nl/vacatures/adviseur"    },    {      "title": "Office manager",      "location": "Utrecht",      "employment_type": "PART_TIME",      "url": "https://voorbeeld.nl/vacatures/office-manager"    }  ],  "technologies": [    {      "name": "Google Analytics",      "category": "analytics",      "version": null,      "support": null    },    {      "name": "WordPress",      "category": "cms",      "version": "6.9",      "support": "current"    },    {      "name": "Cookiebot",      "category": "consent",      "version": null,      "support": null    }  ],  "cms": "WordPress",  "outdated_software": false,  "hosting": {    "provider": "transip",    "dns_provider": "transip",    "cdn": null,    "http3": false  },  "security_headers": [    "strict-transport-security",    "x-content-type-options"  ],  "email_provider": "microsoft",  "mail_security": {    "spf": "softfail",    "dmarc": "quarantine",    "dkim": true,    "bimi": false,    "mta_sts": false  },  "cookie_banner": true,  "consent_platform": "Cookiebot",  "privacy_statement": true,  "tracks_before_consent": false,  "known": {    "count": 35,    "total": 39,    "fields": [      "legal_form",      "active",      "vat_number",      "address",      "building",      "website",      "websites",      "languages",      "services",      "trust_marks",      "apps",      "webshop",      "payment_providers",      "payment_methods",      "shipping_countries",      "phone",      "email",      "social_profiles",      "chat",      "booking",      "booking_tools",      "opening_hours",      "open_vacancies",      "vacancies",      "technologies",      "cms",      "outdated_software",      "hosting",      "security_headers",      "email_provider",      "mail_security",      "cookie_banner",      "consent_platform",      "privacy_statement",      "tracks_before_consent"    ]  }}

Voorbeeld met een fictief bedrijf.

Van nummer tot lijst

Het KVK-nummer komt eerst. Het domein is een gelijkwaardige tweede ingang: heb je alleen een website, bijvoorbeeld uit het e-mailadres bij een aanmelding, dan krijg je hetzelfde antwoord.

Daarna zoeken op wat bedrijven doen en gebruiken, en een lijst in één keer verrijken.

GET /v1/companies/{kvk_number}
Eén bedrijf op zijn KVK-nummer.
GET /v1/companies?domain=voorbeeld.nl
Hetzelfde bedrijf, op zijn domein.
GET /v1/companies
Bedrijven zoeken op wat ze doen en gebruiken.
POST /v1/companies/enrich
Een lijst KVK-nummers in één keer verrijken.

Onbekend is `null`

Een veld dat we niet kennen, is null. Nooit een lege tekst en nooit een nul, zodat je het verschil ziet tussen nee en weten we niet.

Het object known telt de velden die we kennen. Een getal, geen tekst als "6/7": dan kun je erop sorteren en filteren.

count: hoeveel velden we kennen.
total: hoeveel velden een antwoord heeft, zonder kvk_number en name.
fields: de velden die we kennen.

Een false, een 0 of een lege lijst [] is een antwoord, en telt mee als bekend.

Betekenis	Waarde
Bekend	`de waarde`
Nee, nul of geen	`false, 0 of []`
Onbekend	`null`

Notatie

Waarden komen in een vaste vorm, zodat je ze zonder omrekenen opslaat. Hoe je ze toont, kies je zelf: de app laat een telefoonnummer zien als 030 123 45 67.

Veld	Vorm	Voorbeeld
Telefoon	E.164	`+31301234567`
Postcode	zonder spatie	`3511AA`
Land	ISO 3166-1	`NL`
Rechtsvorm, providers	code in kleine letters	`bv`
Bedrag	centen, met currency	`4900`
Datum	ISO 8601	`2026-10-20`

Je API-sleutel

Stuur je sleutel mee in de header Authorization: Bearer <sleutel>. Je maakt je sleutels zelf, in je account.

Per sleutel kun je [aantal] verzoeken per minuut doen. Daarboven krijg je de fout rate_limited.

Fouten

Een fout heeft steeds dezelfde vorm: een object error met een code om in je code op te reageren, een message in het Nederlands en een docs_url naar de uitleg hieronder.

invalid_api_key (401): de sleutel ontbreekt, of we kennen hem niet. Misschien is hij ingetrokken.
invalid_kvk_number (422): een KVK-nummer heeft acht cijfers, zonder spaties of punten.
company_unknown (404): we kennen het nummer niet. Dat zegt niets over het bedrijf.
rate_limited (429): de sleutel zit aan zijn limiet. De header Retry-After zegt na hoeveel seconden je het opnieuw kunt proberen.

GET /v1/companies/00000001

{  "error": {    "code": "company_unknown",    "message": "We kennen KVK-nummer 00000001 niet. Dat zegt niets over het bedrijf.",    "docs_url": "https://achtcijfers.nl/api#company_unknown"  }}

Voorbeeld met een fictief nummer dat we niet kennen.

Wat je per call krijgt

Hoeveel velden een antwoord heeft, kies je met het pakket: Basis, Plus of Tech. Welk veld in welk pakket zit, staat op Velden. Je betaalt per bedrijf, en een nummer dat we niet kennen kost niets. Naar de prijzen.

API