> ## Documentation Index > Fetch the complete documentation index at: https://docs.topograph.co/llms.txt > Use this file to discover all available pages before exploring further. # Netherlands > Country-specific identifiers, data sources, and implementation details ## Start here This guide contains public integration notes for Netherlands. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page. Open the current catalog for supported datapoints, documents, sources, identifiers, and availability. Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support. ## Data Sources The Netherlands uses a single official registry -- the **KVK (Kamer van Koophandel / Chamber of Commerce)** -- accessed through multiple channels. Data retrieval follows a **two-phase model**: basic structured data from the KVK Search API, and detailed data (legal representatives, shareholders, capital, RSIN) from the HTML trade register extract via AI parsing. * **KVK Search API** (`web-api.kvk.nl/zoeken`) -- Provides basic company data in structured JSON: legal name, legal form, status, address, activity description, and trade names. This is a **free, fast API** that returns data immediately. Used for search results and base company profile data. * **KVK Trade Register Extract (Uittreksel Handelsregister)** -- The official HTML extract from the KVK online trade register. Contains detailed data including legal representatives (`Bestuurders`, `Gevolmachtigden`), shareholders (`Aandeelhouders`, `Vennoten`), SBI activity codes, RSIN, share capital, and employee count. This HTML is **AI-parsed** to extract structured data. **Two-phase data retrieval:** Basic company data comes from the KVK Search API (fast, structured JSON). Detailed data (legal representatives, shareholders, capital, RSIN, SBI codes) requires fetching and AI-parsing the HTML trade register extract, which takes longer but provides comprehensive information. The trade register HTML is fetched **once** and reused by multiple data sources (company enrichment, legal representatives, shareholders) via document factorization. ## Company Identifiers ### Query Identifiers | Company Type | Source | Format | Example | Notes | | ---------------- | ------ | --------------------- | ---------- | ---------------------------------------------------------------------- | | **All entities** | KVK | 8 digits (KVK number) | `53781066` | Kamer van Koophandel number -- the universal Dutch business identifier | **KVK Number Format:** The KVK number is always exactly 8 digits. The system validates this with the regex pattern `^\d{8}$`. There is no prefix, no check digit algorithm exposed to the API consumer -- just 8 numeric characters. ### Identifiers in API Response Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity: | Identifier Type | Format | Example | Found In | | --------------- | -------- | ----------- | ------------------------------------------------------------------------- | | `KVK` | 8 digits | `53781066` | All entities (from Search API) | | `RSIN` | 9 digits | `123456789` | Tax/fiscal identification number (from trade register extract, AI-parsed) | **Identifier Casing:** The system uses consistent uppercase `KVK` for the identifier key -- not `kvk` or `KvK`. Always reference identifiers using this casing in API requests and responses. ## Search Capabilities | Search Type | Pattern | Example | Match Type | Expected Results | | ------------- | ----------- | ----------- | ---------- | -------------------------------------------------------------------- | | By KVK Number | 8 digits | `53781066` | Exact | Exact match returned first (matchType: id); other results may follow | | By Name | Text string | `"Philips"` | Fuzzy | Multiple results | **Search Performance:** Use KVK number searches for exact matching and best performance. Name searches query the KVK Search API and return multiple results. Both search types have built-in retry handling for reliability. Name search results are filtered to main establishments only (`Hoofdvestiging`). ## Quirks & Gotchas | Quirk | Details | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Two-phase data retrieval** | Basic company data comes from the KVK Search API (fast, free); detailed data (legal reps, shareholders, capital) requires fetching and AI-parsing the HTML trade register extract. Legal reps and shareholders take longer to return. | | **KVK website access** | KVK website access requires automated session handling. Search and establishment number retrieval are performed against the KVK website. | | **Legal form: two tiers** | Onboarding mode returns 23 base legal forms from the KVK search API. Verification mode extracts the detailed form (48 values) from the trade register document. A BV that is a structuurvennootschap will show as "Besloten Vennootschap" in onboarding and "Besloten Vennootschap (blijkens statuten structuurvennootschap)" in verification. | | **No UBO data** | Ultimate beneficial owner information is not available from the KVK API or trade register extract. The UBO register in the Netherlands is not publicly accessible. | | **Sole shareholders only** | The KVK registers a shareholder only when a company has a **single 100% holder** (`Enig aandeelhouder`). A BV with two or more shareholders publishes no shareholder record at all, so `shareholders` succeeds with an empty list. See [Reading an empty `shareholders` list](#reading-an-empty-shareholders-list). | | **Null ownership percentages** | Ownership percentages are only extracted when **explicitly stated** in the trade register extract. `null` means "not stated", not "0%". The system never infers or calculates percentages. | | **Null nationality** | Nationality is always `null` unless explicitly stated in the document. The system does **not** assume Dutch nationality for shareholders of Dutch companies. | | **SBI codes via AI** | SBI 2008 codes are AI-extracted from the trade register extract HTML. NACE and ISIC are then derived deterministically (no AI). SBI 2025 codes are derived via CBS crosswalk, with LLM disambiguation for ambiguous mappings. In onboarding (no TRE), all codes are AI-inferred from the activity description. | | **Establishment number required** | Document listing and fetching requires the `vestigingsnummer` (establishment number), which is obtained automatically before documents can be listed. | | **Partial document failures** | The three document listing calls (extract, financials, statutes) run in parallel. If one fails, partial results are returned. Only if all three fail is an error thrown. | | **KVK identifier casing** | The system uses consistent `KVK` casing (uppercase) for identifiers, not `kvk` or `KvK`. | | **Statutes listing** | Deposited statutes the register has already checked for personal data are listed and can be ordered for instant download. A recently deposited deed that still contains personal data is not listed, because the register only provides it through a manual redaction request (up to about 2 working days). Core registration facts for a new company (incorporation date, legal form, capital, registered office, directors) already appear in the Trade Register Extract, but the full deed text requires that manual request. | | **Document delivery via email** | Financial statements and statutes are ordered from KVK, delivered via email, then downloaded. This adds latency (\~30 sec). Trade register extracts use a direct online flow. | | **AI model for legal reps** | Legal representative parsing uses GPT-5.1 exclusively (no model racing). The AI extracts birth dates, start dates, roles, and authorization scope. | | **Company self-filtering** | AI parsing sometimes includes the main company itself as a legal representative or shareholder. The system automatically filters these out by matching on KVK number. | ## Company Status Company status is determined **deterministically** from the KVK `actief` boolean field. No AI inference is involved in status determination. | Local Status | English | Standardized Status | Notes | | ------------- | ------------ | ------------------- | ---------------- | | Ingeschreven | Registered | Active | `actief` = true | | Uitgeschreven | Deregistered | Closed | `actief` = false | The KVK provides only a binary active/inactive status. There are no detailed closure reasons (bankruptcy, liquidation, etc.) or insolvency statuses available from the structured API. More detailed status information may occasionally be available in the trade register extract via AI parsing, but it is not systematically extracted. ## Legal Forms The Netherlands has a **two-tier legal form model**. The level of detail you receive depends on the mode you request. * **Onboarding mode** returns **23 base legal forms** from the KVK search API. These are the values in the `rechtsvorm` field (e.g. "Besloten Vennootschap", "Naamloze Vennootschap", "Publiekrechtelijke Rechtspersoon"). This is a deterministic mapping with no AI involved. * **Verification mode** returns **48 detailed legal forms** extracted from the trade register document. These are the `uitgebreideRechtsvorm` values (e.g. "Besloten Vennootschap (blijkens statuten structuurvennootschap)", "Naamloze Vennootschap (beleggingsmaatschappij met veranderlijk kapitaal)", "Publiekrechtelijke Rechtspersoon: Gemeente"). A dedicated AI parser constrained to the 48-value enum extracts the detailed form from the document. Both tiers map to the same standardized categories and ISO 20275 codes. The difference is granularity: onboarding collapses variants into their parent form, while verification resolves the specific subtype. Source: KVK official reference document "Lijst van output: uitgebreide rechtsvormen" (June 2025). ### Onboarding mode (23 base forms) | Dutch Name | English | Standardized | ISO 20275 | | -------------------------------------------------- | ---------------------------------------------- | ------------------------- | --------- | | Eenmanszaak | Sole Proprietorship | `SoleProprietorship` | `4QXM` | | Eenmanszaak met Meerdere Eigenaren | Sole Proprietorship with Multiple Owners | `Other` | `4QXM` | | Rederij | Shipping Company | `Corporation` | `UNJ2` | | Maatschap | Partnership | `Partnership` | `9AAK` | | Vennootschap Onder Firma | General Partnership | `Partnership` | `62Y3` | | Commanditaire Vennootschap | Limited Partnership | `Partnership` | `CODH` | | Rechtspersoon in oprichting | Legal Entity in Formation | `Other` | `EZQW` | | Besloten Vennootschap | Private Limited Company | `LimitedLiabilityCompany` | `54M6` | | Naamloze Vennootschap | Public Limited Company | `Corporation` | `B5PM` | | Coöperatie | Cooperative | `Cooperative` | `NFFH` | | Onderlinge Waarborg Maatschappij | Mutual Guarantee Company | `Cooperative` | `DEO1` | | Vereniging | Association | `NonprofitOrganization` | `33MN` | | Vereniging van Eigenaars | Owners' Association | `Other` | `GNXT` | | Kerkgenootschap | Religious Society or Church | `NonprofitOrganization` | `L7HX` | | Stichting | Foundation | `NonprofitOrganization` | `V44D` | | Overige Privaatrechtelijke Rechtspersoon | Other Private Law Legal Entity | `Other` | `M1IZ` | | Europese naamloze vennootschap (SE) | European Public Limited-Liability Company (SE) | `Corporation` | `BBEB` | | Europees economisch samenwerkingsverband | European Economic Interest Grouping | `Other` | `5WU6` | | Europese coöperatieve vennootschap (SCE) | European Cooperative Society (SCE) | `Cooperative` | `BBEB` | | Kapitaalvennootschap binnen EER | Capital Company within the EEA | `Corporation` | `BBEB` | | Kapitaalvennootschap buiten EER | Capital Company outside the EEA | `Corporation` | `BBEB` | | Overige buitenlandse rechtspersoon of vennootschap | Other Foreign Legal Entity or Company | `Other` | `M1IZ` | | Publiekrechtelijke Rechtspersoon | Public Law Legal Entity | `GovernmentOwnedEntity` | `A0W7` | ### Verification mode (48 detailed forms) In verification mode, the legal form is extracted from the trade register document and resolved to one of 48 specific values. The 23 base forms above still appear when the base and detailed form are the same (e.g. "Eenmanszaak" stays "Eenmanszaak"). The additional 25 detailed variants only appear in verification mode. | Dutch Name | English | Standardized | ISO 20275 | | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------- | --------- | | Besloten Vennootschap | Private Limited Company | `LimitedLiabilityCompany` | `54M6` | | Besloten Vennootschap (blijkens statuten structuurvennootschap) | Private Limited Company (Structure Regime) | `LimitedLiabilityCompany` | `54M6` | | Naamloze Vennootschap | Public Limited Company | `Corporation` | `B5PM` | | Naamloze Vennootschap (blijkens statuten structuurvennootschap) | Public Limited Company (Structure Regime) | `Corporation` | `B5PM` | | Naamloze Vennootschap (beleggingsmaatschappij met veranderlijk kapitaal) | Public Limited Company (Variable Capital Investment Company) | `Corporation` | `B5PM` | | Naamloze Vennootschap (beleggingsmaatschappij met veranderlijk kapitaal blijkens statuten structuurvennootschap) | Public Limited Company (Variable Capital Investment Company, Structure Regime) | `Corporation` | `B5PM` | | Dutch Name | English | Standardized | ISO 20275 | | --------------------------------------------------------------- | ------------------------------------------ | ------------- | --------- | | Coöperatie | Cooperative | `Cooperative` | `NFFH` | | Coöperatie (blijkens statuten structuurcoöperatie) | Cooperative (Structure Regime) | `Cooperative` | `NFFH` | | Onderlinge Waarborg Maatschappij | Mutual Guarantee Company | `Cooperative` | `DEO1` | | Onderlinge Waarborg Maatschappij (blijkens statuten onderlinge) | Mutual Guarantee Company (Mutual Statutes) | `Cooperative` | `DEO1` | | Dutch Name | English | Standardized | ISO 20275 | | -------------------------------------------- | ----------------------------------------- | ----------------------- | --------- | | Vereniging (met volledige rechtsbevoegdheid) | Association (with Full Legal Capacity) | `NonprofitOrganization` | `33MN` | | Vereniging (met beperkte rechtsbevoegdheid) | Association (with Limited Legal Capacity) | `NonprofitOrganization` | `33MN` | In onboarding mode, both appear as "Vereniging". | Dutch Name | English | Standardized | ISO 20275 | | ---------------------------------------------------- | --------------------------------------- | ------------ | --------- | | Overige Privaatrechtelijke Rechtspersoon: Hofje | Other Private Law: Almshouse | `Other` | `M1IZ` | | Overige Privaatrechtelijke Rechtspersoon: Boermarke | Other Private Law: Agricultural Commons | `Other` | `M1IZ` | | Overige Privaatrechtelijke Rechtspersoon: Fundatie | Other Private Law: Endowment | `Other` | `M1IZ` | | Overige Privaatrechtelijke Rechtspersoon: Gilde | Other Private Law: Guild | `Other` | `M1IZ` | | Overige Privaatrechtelijke Rechtspersoon: Buurtschap | Other Private Law: Hamlet Community | `Other` | `M1IZ` | In onboarding mode, all appear as "Overige Privaatrechtelijke Rechtspersoon". Foreign entities registered in the Netherlands. The KVK profile API returns a dynamic `uitgebreideRechtsvorm` with the foreign legal form name and country of establishment (e.g. "Société à responsabilité limitée (Frankrijk)"). The API response normalizes these to one of the 4 base forms below. | Dutch Name | English | Standardized | ISO 20275 | | ------------------------------------------------------------------- | ---------------------------------------------------------- | ------------- | --------- | | Kapitaalvennootschap binnen EER | Capital Company within the EEA | `Corporation` | `BBEB` | | Kapitaalvennootschap buiten EER | Capital Company outside the EEA | `Corporation` | `BBEB` | | Kapitaalvennootschap buiten EER (formeel buitenlandse vennootschap) | Capital Company outside the EEA (formally foreign company) | `Corporation` | `BBEB` | | Overige buitenlandse rechtspersoon of vennootschap | Other Foreign Legal Entity or Company | `Other` | `M1IZ` | | Dutch Name | English | Standardized | ISO 20275 | | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------- | --------- | | Publiekrechtelijke Rechtspersoon: Adviescollege | Public Law: Advisory Council | `GovernmentOwnedEntity` | `A0W7` | | Publiekrechtelijke Rechtspersoon: Bedrijfsvoeringsorganisatie (BVO) | Public Law: Shared Services Organization (BVO) | `GovernmentOwnedEntity` | `A0W7` | | Publiekrechtelijke Rechtspersoon: De Staat (Baten- en lastendienst) | Public Law: The State (Executive Agency) | `GovernmentOwnedEntity` | `A0W7` | | Publiekrechtelijke Rechtspersoon: De Staat (Ministerie) | Public Law: The State (Ministry) | `GovernmentOwnedEntity` | `A0W7` | | Publiekrechtelijke Rechtspersoon: De Staat (Zelfstandig onderdeel) | Public Law: The State (Autonomous Unit) | `GovernmentOwnedEntity` | `A0W7` | | Publiekrechtelijke Rechtspersoon: Europese Groepering voor Territoriale Samenwerking (EGTS) | Public Law: European Grouping of Territorial Cooperation (EGTC) | `GovernmentOwnedEntity` | `A0W7` | | Publiekrechtelijke Rechtspersoon: Gemeente | Public Law: Municipality | `GovernmentOwnedEntity` | `A0W7` | | Publiekrechtelijke Rechtspersoon: Lichaam met bevoegdheid krachtens de Grondwet | Public Law: Body with Constitutional Authority | `GovernmentOwnedEntity` | `A0W7` | | Publiekrechtelijke Rechtspersoon: Openbaar Lichaam op basis van gemeenschappelijke regeling | Public Law: Public Body under Joint Arrangement | `GovernmentOwnedEntity` | `A0W7` | | Publiekrechtelijke Rechtspersoon: Provincie | Public Law: Province | `GovernmentOwnedEntity` | `A0W7` | | Publiekrechtelijke Rechtspersoon: Rechtspersoon met Wettelijk Taak (RWT) | Public Law: Entity with Statutory Task (RWT) | `GovernmentOwnedEntity` | `A0W7` | | Publiekrechtelijke Rechtspersoon: Universiteit of Academisch Ziekenhuis | Public Law: University or Academic Hospital | `GovernmentOwnedEntity` | `A0W7` | | Publiekrechtelijke Rechtspersoon: Waterschap | Public Law: Water Board | `GovernmentOwnedEntity` | `A0W7` | | Publiekrechtelijke Rechtspersoon: Zelfstandig Bestuursorgaan (ZBO) | Public Law: Independent Administrative Body (ZBO) | `GovernmentOwnedEntity` | `A0W7` | In onboarding mode, all appear as "Publiekrechtelijke Rechtspersoon". ## Legal Representatives Legal representatives come from the KVK trade register extract. You get a person's name, birth date, start date, and a role that always comes from a fixed list. ### A closed role list We use a **closed list of canonical roles** for the Netherlands. Every `role.localName` you receive in the API response is guaranteed to be one of these values. The list is built on top of **ISO 5009**, the international standard for official organizational roles published by ISO and maintained by GLEIF. ISO 5009 covers the statutory roles defined in the Dutch Civil Code (directors, supervisory board members, liquidators, and so on). We took the Dutch entries from the ISO 5009 code list and deduplicated them into canonical roles. On top of that, we added four roles that appear on Dutch trade register extracts but are out of scope for ISO 5009 because they are based on power of attorney (volmacht) rather than corporate governance: * **Gevolmachtigde** and **Gevolmachtigd handelsagent**, registered via KVK Form 13 * **Procuratiehouder**, a historical commercial volmacht role * **Bewindvoerder**, a trustee appointed during suspension of retrievals Shareholder roles (Aandeelhouder, Vennoot, Eigenaar) are not part of this list. They live in the `shareholders` field of the API response. ### Full role enum The 20 canonical role values you may receive in the `role.localName` field. Each ISO 5009 role can map to multiple OOR codes because the code depends on the legal form of the company. For example, "Bestuurder" is `KHNVNO` for a BV, `TK4BXG` for an NV, and `PPIUMW` for a Stichting. | Dutch name | English | Standardized | ISO 5009 OOR codes | | ------------------------------- | ---------------------------------- | ----------------------------- | ----------------------------------------------------------------- | | Bestuurder | Director | `Director` | KHNVNO (BV), TK4BXG (NV), PPIUMW (Stichting) | | Bestuurder / bestuurslid | Director / Board Member | `Director` | W9JQJP (Vereniging) | | Uitvoerend bestuurder | Executive Director | `ExecutiveDirector` | TFPVDK (BV), 7BGHMI (NV) | | Niet uitvoerend bestuurder | Non-Executive Director | `NonExecutiveDirector` | VA30FP (BV), HHZHF9 (NV) | | Voorzitter bestuur | Chairman of the Management Board | `Chairman` | 080BGK (BV), 934G9A (NV) | | Voorzitter | Chairman | `Chairman` | 9W99BU (Vereniging) | | Commissaris | Supervisory Board Member | `SupervisoryBoardMember` | GRP0OJ (BV), TP7XTW (NV), RERTFR (Stichting), LMY8OH (Vereniging) | | Voorzitter raad van commissaren | Chairman of the Supervisory Board | `ChairmanOfSupervisoryBoard` | WPGA3Y (NV) | | Secretaris | Secretary | `Secretary` | PV9S1F (Vereniging) | | Penningmeester | Treasurer | `Treasurer` | GQ8JOW (Vereniging) | | Vertegenwoordigingsbevoegde | Authorized Signatory (statutory) | `AuthorizedSignatory` | CHOFER (BV), RPL5H6 (NV), SXRUU6 (Vereniging), WNHFP9 (Stichting) | | Vereffenaar | Liquidator | `Liquidator` | 7PTVPF (BV), WBJNBK (NV) | | Curator | Court-Appointed Administrator | `CourtAppointedAdministrator` | ALIVPM (NV), SYLJPO (BV) | | Beheerder | Administrator | `Administrator` | OIEAWD (Maatschap) | | Beheerder / Beherend Vennoot | Managing Partner | `ManagingPartner` | BF4XP2 (VOF) | | Beherend Vennoot | General Partner | `GeneralPartner` | BKH1IX (CV) | | Gevolmachtigde | Authorized Representative | `AuthorizedRepresentative` | Topograph extension (Boek 3 volmacht) | | Gevolmachtigd handelsagent | Authorized Commercial Agent | `AuthorizedCommercialAgent` | Topograph extension (Boek 3 volmacht) | | Procuratiehouder | Procurator | `Procurator` | Topograph extension (historical volmacht) | | Bewindvoerder | Trustee (suspension of retrievals) | `Trustee` | Topograph extension (Boek 3 bewind) | ### Role normalization Dutch trade register extracts sometimes use informal variants or add authority scope to a role name. We normalize these to the canonical value so you always get a predictable result. | What the extract says | What you receive | | --------------------------------------------------- | ---------------- | | Directeur, Statutair bestuurder, Algemeen directeur | Bestuurder | | Bestuurder - Alleen/zelfstandig bevoegd | Bestuurder | | Bestuurder - Gezamenlijk bevoegd | Bestuurder | | CEO, CFO, COO | Bestuurder | | Gevolmachtigde - Beperkte volmacht | Gevolmachtigde | | Gevolmachtigde - Onbeperkte volmacht | Gevolmachtigde | Signing authority (sole or joint) is kept as a separate `representationMode` field on the response, not mixed into the role. ### Fields extracted per legal representative | Field | Dutch source term | Description | | ---------- | -------------------- | ----------------------------------- | | Birth date | Geboortedatum | Date of birth | | Start date | Datum in functie | Date the person started in the role | | Role | (from the extract) | One of the canonical values above | | Name title | Mr., Mrs., Dr., etc. | Honorific prefix only | ## Other Key Persons Two roles appear on Dutch trade register extracts but are not legal representatives. They are returned separately: | Dutch name | English | Standardized | ISO 5009 OOR codes | | ---------- | ------- | ------------ | -------------------------------------------- | | Oprichter | Founder | `Founder` | AJ86T4 (BV), 6ITGMW (NV), KLUFYX (Stichting) | | Lid | Member | `Member` | 1AHQJK (Vereniging) | ## Shareholders Shareholders are extracted from the KVK trade register extract HTML via **AI parsing**, using the same HTML document as legal representatives (fetched once via document factorization). ### Dutch Terms for Shareholders | Dutch Term | English | Entity Type | Found In | | -------------- | ------------ | --------------------------------- | -------------------- | | Aandeelhouders | Shareholders | BV, NV companies | Capital companies | | Vennoten | Partners | VOF, CV partnerships | Partnerships | | Eigenaar | Owner | Eenmanszaak (sole proprietorship) | Sole proprietorships | ### Extraction Logic | Source | When Used | Data Extracted | | ------------------------------- | ------------------ | ------------------------------------------------------------------------ | | **Trade Register Extract HTML** | Always (AI-parsed) | Partners, Shareholders, Owners with names and optional share percentages | ### Ownership Fields | Field | Description | Source | | ----------------- | --------------------- | ---------------------------------------------------------------------- | | `sharePercentage` | Ownership percentage | Only if **explicitly stated** in document (null if not stated) | | `type` | Individual or Company | Determined from AI parsing context | | `nationality` | Nationality | Only if **explicitly stated** (null by default -- never assumes Dutch) | **Critical: Ownership Percentages** Share percentages are only extracted when explicitly stated in the trade register extract (e.g., "50%", "33,33%"). The system does **not** infer or calculate percentages. If no percentage is mentioned, `sharePercentage` is `null`. Do not assign 100% to each shareholder. Nationality is also `null` unless explicitly stated -- the system does not assume Dutch nationality. Shareholder data is available for BV/NV companies, VOF/CV partnerships (as partners), and Eenmanszaak (as owner). Stichtingen (foundations) and Verenigingen (associations) do **not** have shareholders. ### Reading an empty `shareholders` list Dutch law only obliges a company to register its shareholder when there is **exactly one** holding 100% of the shares (`Enig aandeelhouder`, art. 2:194 BW). A BV or NV with two or more shareholders registers **nothing** — the Handelsregister simply has no shareholder record for it, and neither does the Uittreksel. So for the Netherlands: | Response | Meaning | | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `shareholders: [ { … 100% } ]` | The company has a registered sole shareholder. | | `shareholders: []` with `status: "succeeded"` | The register holds **no shareholder record**. Almost always a company with two or more shareholders — **not** a company without owners. | | `shareholders` key absent | The datapoint was not requested, failed, or is still running. Check `dataStatus`. | An empty `shareholders` list is **not** a terminal node in an ownership chain. It means the Dutch register does not publish this company's ownership, not that the chain ends. Measured across 4,322 real KVK extracts: 2,435 carry a sole shareholder and only 2 carry a multi-holder list. When the list is empty and you need to continue the traversal: * **`legalRepresentatives`** — a Dutch holding structure is very often managed by its own parent, so a corporate `Bestuurder` with its own KVK number is usually the next entity up. * **Trade Register History** (`Uittreksel Handelsregister Historie`) — shows any sole-shareholder registration the company has had in the past, with start and end dates. If the history has none either, the company has never had a registered sole shareholder. * **Financial Statements** (`Jaarrekeningen`) — consolidated accounts frequently name the parent in the notes. * **Deed of incorporation / statutory amendment** (`Akte van oprichting` / `Statutenwijziging`) — the notarial deed names the subscribing shareholders at the time it was executed. ## Activity Code Mapping The Netherlands uses the **SBI (Standaard Bedrijfsindeling)** classification. SBI 2008 codes (5-digit) are extracted from the trade register extract via AI parsing. From these, **NACE Rev 2** and **ISIC Rev 4** codes are derived **deterministically** (no AI), and **SBI 2025** codes are derived via the official CBS crosswalk (with LLM disambiguation for ambiguous mappings). ### Company Profile (with Trade Register Extract) ``` TRE (AI-parsed) → SBI 2008 codes → truncate to 4 digits + insert dot → NACE Rev 2 (deterministic) → formal ISIC↔NACE mapping → ISIC Rev 4 (deterministic) → CBS crosswalk → SBI 2025 (1:1 resolved or LLM-disambiguated) ``` | Classification | Source | Example | AI Inferred? | | -------------- | --------------------------------------- | ------- | ------------------------------------------------------- | | **SBI 2025** | Derived from SBI 2008 via CBS crosswalk | `47120` | Yes (AI-extracted from HTML + crosswalk disambiguation) | | **NACE Rev 2** | Derived from SBI 2008 (truncate + dot) | `47.19` | No (deterministic) | | **ISIC Rev 4** | Formal mapping from NACE | `4719` | No (deterministic) | ### Onboarding Profile (Search API only, no TRE) ``` Activity description (activiteitomschrijving) → LLM inference → ISIC codes → formal ISIC↔NACE mapping → NACE Rev 2 (deterministic) → CBS crosswalk → SBI 2025 (1:1 resolved or LLM-disambiguated) ``` | Classification | Source | Example | AI Inferred? | | -------------- | -------------------------------------- | ------- | -------------------------------- | | **SBI 2025** | Derived from NACE via CBS crosswalk | `64110` | Yes | | **NACE Rev 2** | Derived from ISIC (formal mapping) | `64.11` | Yes (source ISIC is AI-inferred) | | **ISIC Rev 4** | LLM-inferred from activity description | `6411` | Yes | **Deterministic vs. AI-inferred:** When the trade register extract is available (company profile), NACE and ISIC are derived deterministically from SBI 2008 codes (`isAIInferred: false`). SBI 2025 codes use the CBS crosswalk \-- 1:1 mappings are resolved automatically, ambiguous mappings (multiple SBI 2025 candidates for one NACE code) are disambiguated by an LLM using the company's activity description. When only the search API is available (onboarding profile), all codes are AI-inferred from the activity description text. ## Data Availability Matrix | Data Type | BV/NV | VOF/CV | Eenmanszaak | Stichting/Vereniging | Notes | | -------------------------- | ------- | --------------- | ------------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | Company Profile | ✅ Async | ✅ Async | ✅ Async | ✅ Async | Basic data from Search API + AI enrichment from trade register | | Legal Representatives | ✅ | ✅ | ✅ | ✅ | AI-parsed from trade register extract HTML | | Shareholders | ✅ | ✅ (as partners) | ✅ (as owner) | ❌ | AI-parsed; VOF/CV show partners, EMZ shows owner | | Ultimate Beneficial Owners | ❌ | ❌ | ❌ | ❌ | Not available from KVK (UBO register not publicly accessible) | | Establishments | ❌ | ❌ | ❌ | ❌ | Not yet implemented | | Activity Codes | ✅ | ✅ | ✅ | ✅ | SBI 2025, NACE, ISIC. Company profile: SBI 2008 from TRE → deterministic NACE/ISIC. Onboarding: AI-inferred from description. | **Legend:** ✅ Available | ❌ Not Available | ⚠️ Conditionally Available | Async = Asynchronous processing ## Documents by Company Type ### All Companies | Document Type | API Category | Format | Catalog item | Availability | Notes | | ------------------------------------------------------- | ------------------------- | ------ | -------------------------- | ---------------- | ------------------------------------------------------------------------------ | | **Uittreksel Handelsregister (Trade Register Extract)** | `tradeRegisterExtract` | PDF | `NLD_REGISTER_EXTRACT` | ✅ When available | Online extract from KVK (\~30 sec, 24h fast search dataset) | | **Jaarrekening (Financial Statements)** | `financialStatements[]` | PDF | `NLD_FINANCIAL_STATEMENTS` | ✅ When filed | Annual accounts from KVK (delivered via email, 99-year fast search dataset) | | **Statuten (Articles of Association)** | `articlesOfAssociation[]` | PDF | `NLD_STATUS` | ✅ When filed | Corporate statutes from KVK (delivered via email, 99-year fast search dataset) | **Trade Register Extract:** The Uittreksel is an HTML document fetched from the KVK website and converted to PDF for delivery. The HTML content is AI-parsed to extract structured data. **Document Delivery Methods:** The trade register extract uses a direct **online flow** (fast, \~30 sec). Financial statements and statutes use a **mail flow**: the document is ordered from KVK, delivered via email, then downloaded and saved. This adds latency but is the only retrieval method available for these document types. **Document Listing:** Documents are listed via three parallel KVK API calls: (1) trade register extract availability, (2) financial statements, (3) statutes. If one source fails, partial results are still returned. Only if all three fail is an error thrown. ## Example API Responses All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "NL", "dataPoints": ["company", "legalRepresentatives"] }` ```json theme={null} { "company": { "id": "12345678", "countryCode": "NL", "identifiers": { "KVK": "12345678", "RSIN": "123456789" }, "legalName": "Voorbeeld Tech B.V.", "activityDescription": "Ontwikkeling van software en IT-diensten.", "status": { "localName": "Ingeschreven", "active": true, "statusDetails": { "status": "ACTIVE" } }, "legalForm": { "localName": "Besloten Vennootschap", "englishTranslation": "Private Limited Company", "standardized": "Limited Liability Company", "iso20275Code": "54M6" }, "capital": { "amount": 100000, "currency": "EUR" }, "activities": { "SBI": [{ "code": "62010", "description": "Ontwikkeling en productie van software", "isAIInferred": true }], "NACE": [{ "code": "62.01", "description": "Computer programming activities", "isAIInferred": false }], "ISIC": [{ "code": "6201", "description": "Computer programming activities", "isAIInferred": false }] }, "legalAddress": { "addressLine1": "Herengracht 100", "city": "Amsterdam", "postalCode": "1015 AA", "countryCode": "NL" } }, "legalRepresentatives": [ { "type": "individual", "role": { "localName": "Bestuurder", "standardized": "Director" }, "individual": { "name": { "fullName": "Jan de Vries" }, "birthDate": { "year": 1980, "month": 5, "day": 15 } } }, { "type": "individual", "role": { "localName": "Gevolmachtigde", "standardized": "Authorized Representative" }, "individual": { "name": { "fullName": "Anna Bakker" }, "birthDate": { "year": 1985, "month": 9 } } } ], "shareholders": [ { "type": "individual", "sharePercentage": null, "individual": { "name": { "fullName": "Jan de Vries" } } }, { "type": "company", "sharePercentage": 60, "company": { "legalName": "Holding Groep B.V.", "id": "87654321" } } ] } ``` ```json theme={null} { "company": { "id": "98765432", "countryCode": "NL", "identifiers": { "KVK": "98765432" }, "legalName": "Oude Fabriek N.V.", "activityDescription": "Vervaardiging van textielproducten.", "status": { "localName": "Uitgeschreven", "active": false, "statusDetails": { "status": "CLOSED" } }, "legalForm": { "localName": "Naamloze Vennootschap", "englishTranslation": "Public Limited Company", "standardized": "Corporation", "iso20275Code": "B5PM" }, "activities": { "SBI": [{ "code": "13200", "description": "Weven van textiel", "isAIInferred": true }], "NACE": [{ "code": "13.20", "description": "Weaving of textiles", "isAIInferred": false }], "ISIC": [{ "code": "1312", "description": "Weaving of textiles", "isAIInferred": false }] }, "legalAddress": { "addressLine1": "Industrieweg 25", "city": "Rotterdam", "postalCode": "3024 AA", "countryCode": "NL" } }, "legalRepresentatives": [ { "type": "individual", "role": { "localName": "Bestuurder", "standardized": "Director" }, "individual": { "name": { "fullName": "Pieter Jansen" }, "birthDate": { "year": 1965, "month": 3 } } } ] } ``` **Note:** Closed companies have `active: false` and status `Uitgeschreven` (Deregistered). No detailed closure reason is available from the KVK. ```json theme={null} { "company": { "id": "87654321", "countryCode": "NL", "identifiers": { "KVK": "87654321" }, "legalName": "Bakkerij van den Berg V.O.F.", "activityDescription": "Vervaardiging van brood en banketbakkerswerk.", "status": { "localName": "Ingeschreven", "active": true, "statusDetails": { "status": "ACTIVE" } }, "legalForm": { "localName": "Vennootschap Onder Firma", "englishTranslation": "General Partnership", "standardized": "Partnership", "iso20275Code": "62Y3" }, "legalAddress": { "addressLine1": "Kalverstraat 50", "city": "Utrecht", "postalCode": "3511 AA", "countryCode": "NL" } }, "legalRepresentatives": [ { "type": "individual", "role": { "localName": "Vennoot", "standardized": "Partner" }, "individual": { "name": { "fullName": "Pieter van den Berg" } } }, { "type": "individual", "role": { "localName": "Vennoot", "standardized": "Partner" }, "individual": { "name": { "fullName": "Maria van den Berg" } } } ], "shareholders": [ { "type": "individual", "sharePercentage": null, "individual": { "name": { "fullName": "Pieter van den Berg" } } }, { "type": "individual", "sharePercentage": null, "individual": { "name": { "fullName": "Maria van den Berg" } } } ] } ``` **Note:** VOF partners (`Vennoten`) appear as both legal representatives and shareholders. Ownership percentages are typically not stated for partnerships, so `sharePercentage` is `null`. ```json theme={null} { "company": { "id": "11223344", "countryCode": "NL", "identifiers": { "KVK": "11223344" }, "legalName": "Consultancy Van Dijk", "activityDescription": "Advisering op het gebied van management en bedrijfsvoering.", "status": { "localName": "Ingeschreven", "active": true, "statusDetails": { "status": "ACTIVE" } }, "legalForm": { "localName": "Eenmanszaak", "englishTranslation": "Sole Proprietorship", "standardized": "Sole Proprietorship", "iso20275Code": "4QXM" }, "legalAddress": { "addressLine1": "Keizersgracht 200", "city": "Amsterdam", "postalCode": "1016 AA", "countryCode": "NL" } }, "shareholders": [ { "type": "individual", "sharePercentage": null, "individual": { "name": { "fullName": "Sophie van Dijk" } } } ] } ``` **Note:** For sole proprietorships, the owner (`Eigenaar`) appears as a shareholder. The entrepreneur is the company itself. ```json theme={null} { "company": { "id": "55667788", "countryCode": "NL", "identifiers": { "KVK": "55667788" }, "legalName": "Stichting Kunstbehoud Nederland", "activityDescription": "Behoud en promotie van Nederlands cultureel erfgoed.", "status": { "localName": "Ingeschreven", "active": true, "statusDetails": { "status": "ACTIVE" } }, "legalForm": { "localName": "Stichting", "englishTranslation": "Foundation", "standardized": "Nonprofit Organization", "iso20275Code": "V44D" }, "legalAddress": { "addressLine1": "Museumplein 10", "city": "Amsterdam", "postalCode": "1071 DJ", "countryCode": "NL" } }, "legalRepresentatives": [ { "type": "individual", "role": { "localName": "Bestuurder", "standardized": "Director" }, "individual": { "name": { "fullName": "Willem de Groot" }, "birthDate": { "year": 1970, "month": 8, "day": 20 } } } ] } ``` **Note:** Foundations (Stichtingen) have no shareholders -- they are non-profit entities with a board of directors (`Bestuurders`). No UBOs are available from the KVK. Documents are returned when `"dataPoints": ["availableDocuments"]` is requested. | API Category | Document | Notes | | ------------------------- | ------------------------------ | -------------------------------------- | | `tradeRegisterExtract` | Uittreksel Handelsregister PDF | When available (\~30 sec, online flow) | | `financialStatements[]` | Jaarrekening (annual accounts) | When filed, PDF format (mail flow) | | `articlesOfAssociation[]` | Statuten (corporate statutes) | When filed, PDF format (mail flow) |