{ "openapi": "3.1.0", "info": { "title": "KVK API suite", "version": "0.0.1", "description": "De KVK API suite biedt endpoints om bedrijfsinformatie op te vragen. Controleer de geldigheid van bedrijfsgegevens en verkrijg gedetailleerde informatie over bedrijven.\n\n## Authentication\n\nAll API endpoints require authentication. Include your API key in every request using **one** of the following methods:\n\n**Option 1 \u2014 X-Api-Key header (recommended)**\n```\nX-Api-Key: ga_live_xxxxxxxxxxxxxxxxxxxx\n```\n\n**Option 2 \u2014 Bearer token**\n```\nAuthorization: Bearer ga_live_xxxxxxxxxxxxxxxxxxxx\n```\n\nYou can generate and manage API keys in your [dashboard](https://getapi.nl/dashboard).\n\n## AI & Agent Payments (x402)\n\nSome endpoints support direct payments for AI agents via the **x402** protocol (https://www.x402.org).\nNo API key or account is needed. Send a normal request without key;\nthe server will respond with **HTTP 402** and a `PAYMENT-REQUIRED` header:\n\n```\nPAYMENT-REQUIRED: \n```\n\nThis base64 string contains, among other things, `network`, `asset`, `amount`, and `payTo`. \nYour agent signs an EIP-3009 *transferWithAuthorization* for the specified `amount` of USDC to that `payTo` address, \nencodes the signature as base64, and resubmits the request with:\n\n```\nPAYMENT-SIGNATURE: \n```\n\nThe server verifies the signature via a facilitator, provides the data, and settles the payment on-chain. \nThe success response includes a `PAYMENT-RESPONSE` header containing the transaction information. \nA one-time `nonce` prevents replay attacks. Payments are made in USDC on **Base**; \nthe price is determined by the `credit_cost` of the endpoint.", "contact": { "email": "info@wdnoord.nl" }, "x-guidance": "GetAPI.nl is een Nederlandse API-platform voor lookups en validaties (postcode,\nadres, kenteken, BTW, e-mail, KVK, IBAN, energiemaatwerk, overheidsdata). Elke\nendpoint accepteert een API key via de X-Api-Key header of Authorization:\nBearer .\n\nSommige endpoints zijn ook direct betaalbaar voor AI-agents via het x402-protocol\n(https://www.x402.org) zonder account of API key: stuur een verzoek zonder key,\nde server antwoordt met HTTP 402 en een PAYMENT-REQUIRED header (base64 JSON met\nnetwork, asset, amount, payTo). Teken daarna een EIP-3009 transferWithAuthorization\nvoor het gevraagde bedrag in USDC op Base en hertrail met een PAYMENT-SIGNATURE\nheader. De server verifieert, levert de data en settleert on-chain.\n\nTips voor agents:\n- Lees eerst de PAYMENT-REQUIRED header van een 402-antwoord; die is leidend.\n- Geef altijd de exact door de server gevraagde parameters mee.\n- Een endpoint met een \"x-payment-info\" blok vereist betaling voor gebruik." }, "servers": [ { "url": "https://api.getapi.nl", "description": "GetAPI" } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "paths": { "/v1/validate/kvk": { "post": { "operationId": "validation.kvk", "description": "Validates an 8-digit KVK number against the official KVK Handelsregister\nAPI (developers.kvk.nl). Voor actuele data wordt altijd KVK geraadpleegd;\nlokale cache (48 uur) dient alleen voor herhaalde requests. `lastFetchedAt`\ntoont wanneer de data voor het laatst bij KVK is opgehaald.\nOptioneel: `?vies=true` of `?vat=true` valideert het afgeleide btw-nummer\nvia VIES (gratis, extra latency). Returns whether the registration is active,\nits legal form (rechtsvorm), the start date and the SBI-activities. It does\n**not** expose company names, full addresses or other personal data.\n\nKVK rate-limits this endpoint to 1 request/minute per IP, so results are\ncached 48 uur. When KVK is unreachable we return HTTP 502/503.", "summary": "Validate a Dutch KVK number (Handelsregister)", "tags": [ "KVK / Handelsregister", "Kvk" ], "parameters": [ { "name": "vies", "in": "query", "description": "Valideer afgeleid btw-nummer via VIES (`vies=true`). Alias voor `vat`.", "schema": { "type": "string" } }, { "name": "vat", "in": "query", "description": "Valideer afgeleid btw-nummer via VIES (`vat=true`).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kvk_number": { "type": "string", "pattern": "^\\d{8}$" }, "vies": { "type": "string", "enum": [ "true", "false", "1", "0" ] }, "vat": { "type": "string", "enum": [ "true", "false", "1", "0" ] } }, "required": [ "kvk_number" ] } } } }, "responses": { "200": { "description": "KVK number is registered", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "found": true, "valid": true, "kvk_number": "59581883", "actief": true, "rechtsvorm": "BV", "insolventie": null, "insolventie_omschrijving": null, "datum_aanvang": "2010-12-31", "postcode_regio": 15, "postcode_regio_code": "15**", "lidstaat": "NL", "activiteiten": [ { "sbi_code": "5630", "soort": "hoofdactiviteit" } ], "message": "KVK-nummer is geregistreerd en actief.", "error": null, "retry_after": null } ], "properties": { "found": { "type": "boolean" }, "valid": { "type": "boolean" }, "kvk_number": { "type": "string" }, "actief": { "type": [ "boolean", "null" ] }, "rechtsvorm": { "type": [ "string", "null" ] }, "insolventie": { "type": [ "string", "null" ] }, "insolventie_omschrijving": { "type": [ "string", "null" ] }, "datum_aanvang": { "type": [ "string", "null" ] }, "postcode_regio": { "type": [ "integer", "null" ] }, "postcode_regio_code": { "type": [ "string", "null" ] }, "lidstaat": { "type": [ "string", "null" ] }, "activiteiten": { "type": "array", "items": { "type": "object", "properties": { "sbi_code": { "type": "string" }, "soort": { "type": "string" } }, "required": [ "sbi_code", "soort" ] } }, "lastFetchedAt": { "type": [ "string", "null" ] }, "vat": { "type": [ "object", "null" ], "properties": { "number": { "type": "string" }, "rsin": { "type": "string" }, "checksumValid": { "type": "boolean" }, "valid": { "type": [ "boolean", "null" ] }, "status": { "type": "string" }, "validatedAt": { "type": [ "string", "null" ] } }, "required": [ "number", "rsin", "checksumValid", "valid", "status", "validatedAt" ] }, "message": { "type": "string" }, "error": { "type": [ "string", "null" ] }, "retry_after": { "type": [ "integer", "null" ] } }, "required": [ "found", "valid", "kvk_number", "actief", "rechtsvorm", "insolventie", "insolventie_omschrijving", "datum_aanvang", "postcode_regio", "postcode_regio_code", "lidstaat", "activiteiten", "lastFetchedAt", "vat", "message", "error", "retry_after" ] } } } }, "422": { "description": "KVK number is not registered", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "found": false, "valid": false, "kvk_number": "11111111", "actief": null, "rechtsvorm": null, "insolventie": null, "insolventie_omschrijving": null, "datum_aanvang": null, "postcode_regio": null, "postcode_regio_code": null, "lidstaat": null, "activiteiten": [], "message": "KVK-nummer is niet geregistreerd in het Handelsregister.", "error": null, "retry_after": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "503": { "description": "KVK Open Data temporarily unavailable", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "found": null, "valid": null, "kvk_number": "59581883", "actief": null, "rechtsvorm": null, "insolventie": null, "insolventie_omschrijving": null, "datum_aanvang": null, "postcode_regio": null, "postcode_regio_code": null, "lidstaat": null, "activiteiten": [], "message": "De KVK Open Data-bron (3rd party) heeft een frequentielimiet van 1 verzoek per minuut bereikt. Probeer het over een minuut opnieuw.", "error": "source_rate_limited", "retry_after": 60 }, { "found": null, "valid": null, "kvk_number": "59581883", "actief": null, "rechtsvorm": null, "insolventie": null, "insolventie_omschrijving": null, "datum_aanvang": null, "postcode_regio": null, "postcode_regio_code": null, "lidstaat": null, "activiteiten": [], "message": "KVK Open Data is tijdelijk niet bereikbaar. Probeer het later opnieuw.", "error": "upstream_unavailable", "retry_after": null } ] } } } } } } }, "/v1/kvk/search": { "get": { "operationId": "kvk.search", "description": "Directe passthrough naar KVK Handelsregister Zoeken API. Velden conform\nKVK: `kvkNummer`, `vestigingsnummer`, `naam`, `adres.binnenlandsAdres`,\n`type` (`rechtspersoon`/`hoofdvestiging`/`nevenvestiging`). Voor actuele\ndata wordt altijd KVK geraadpleegd; lokale zoek-cache (48 uur) dient\nalleen voor herhaalde queries binnen 48 uur. `lastFetchedAt` toont laatste\nophaaldatum.", "summary": "Zoeken in KVK Handelsregister", "tags": [ "KVK / Handelsregister", "KvkSearch" ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "pagina": 1, "resultatenPerPagina": 10, "totaal": 1, "resultaten": [ { "kvkNummer": "68750110", "naam": "Test BV Donald", "adres": { "binnenlandsAdres": { "type": "bezoekadres", "straatnaam": "Hizzaarderlaan", "plaats": "Lollum" } }, "type": "hoofdvestiging", "links": [ { "rel": "basisprofiel", "href": "..." } ] } ], "lastFetchedAt": "2026-10-08T12:00:00+00:00", "links": [ { "rel": "self", "href": "..." } ] } ] } } } }, "404": { "description": "No results", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "fout": [ { "code": "IPD5200", "omschrijving": "Er zijn geen gegevens gevonden." } ] } ] } } } } } } }, "/v1/kvk/{companyNumber}": { "get": { "operationId": "kvk.detail", "description": "Geeft het KVK Handelsregister basisprofiel voor een 8-cijferig KVK-nummer.\nVelden conform KVK Handelsregister API: `kvkNummer`, `naam`, `handelsnamen`,\n`sbiActiviteiten`, `_embedded.eigenaar`/`hoofdvestiging` (incl. `rsin`,\n`rechtsvorm`), `adressen` en `links`. Voor actuele data wordt altijd\nKVK geraadpleegd; lokale cache (48 uur) dient alleen voor herhaalde\nrequests binnen 48 uur. `lastFetchedAt` toont wanneer de data voor het\nlaatst bij KVK is opgehaald. Optioneel: `vat=true`/`vies=true` leidt het\nbtw-nummer af uit `rsin` en valideert via EU VIES (gratis, extra latency).", "summary": "KVK detail (basisprofiel)", "tags": [ "KVK / Handelsregister", "KvkDetail" ], "parameters": [ { "name": "companyNumber", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "vat", "in": "query", "description": "Voeg derived VAT toe en valideer optioneel via VIES (`vat=true`). Alias: `vies`.", "schema": { "type": "string" } }, { "name": "vies", "in": "query", "description": "Alias voor `vat` \u2013 valideer VAT via VIES (`vies=true`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Company basisprofiel", "content": { "application/json": { "schema": { "examples": [ { "kvkNummer": "68750110", "naam": "Test BV Donald", "indNonMailing": "Nee", "formeleRegistratiedatum": "20170519", "handelsnamen": [ { "naam": "Test BV Donald", "volgorde": 0 } ], "sbiActiviteiten": [ { "sbiCode": "01241", "sbiOmschrijving": "Teelt van appels en peren", "indHoofdactiviteit": "Ja" } ], "actief": true, "hoofdvestiging": { "vestigingsnummer": "000037178598", "eersteHandelsnaam": "Test BV Donald", "indHoofdvestiging": "Ja", "indCommercieleVestiging": "Ja", "adressen": [] }, "vat": { "number": "NL68750110B01", "rsin": "68750110", "checksumValid": true, "valid": null, "status": "unvalidated", "validatedAt": null }, "lastFetchedAt": "2026-10-08T12:00:00+00:00", "links": [ { "rel": "self", "href": "..." } ] } ], "anyOf": [ { "type": "string" }, { "type": "array", "items": [] } ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "fout": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "code": { "type": "string", "const": "IPD0004" }, "omschrijving": { "type": "string" } }, "required": [ "code", "omschrijving" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "fout" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "fout": [ { "code": "IPD0005", "omschrijving": "Op basis van het KVK-nummer kan het product niet worden geleverd." } ] } ] } } } } } } }, "/v1/kvk/{companyNumber}/branch": { "get": { "operationId": "kvk.detail.branch", "description": "Geeft het KVK Handelsregister vestigingsprofiel voor een 12-cijferig\nvestigingsnummer. Velden conform KVK: `vestigingsnummer`, `kvkNummer`,\n`eersteHandelsnaam`, `indHoofdvestiging`, `handelsnamen`, `adressen`,\n`websites`, `sbiActiviteiten`. Voor actuele data wordt altijd KVK\ngeraadpleegd (lokale cache 48 uur). `lastFetchedAt` toont laatste\nophaaldatum.", "summary": "KVK vestigingsprofiel", "tags": [ "KVK / Handelsregister", "KvkBranch" ], "parameters": [ { "name": "companyNumber", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Vestigingsprofiel", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "vestigingsnummer": "000037178598", "kvkNummer": "68750110", "eersteHandelsnaam": "Test BV Donald", "indHoofdvestiging": "Ja", "indCommercieleVestiging": "Ja", "handelsnamen": [ { "naam": "Test BV Donald", "volgorde": 0 } ], "adressen": [], "websites": [], "sbiActiviteiten": [], "lastFetchedAt": "2026-10-08T12:00:00+00:00", "links": [ { "rel": "self", "href": "..." } ] } ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "fout": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "code": { "type": "string", "const": "IPD0006" }, "omschrijving": { "type": "string" } }, "required": [ "code", "omschrijving" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "fout" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "fout": [ { "code": "IPD0006", "omschrijving": "Het vestigingsnummer is niet valide." } ] } ] } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "BearerAuth": { "type": "http", "scheme": "bearer" } } } }