openapi: 3.0.1 info: title: Vestigingen API description: Opvragen van een vestiging termsOfService: https://www.kvk.nl/over-het-handelsregister/gebruikersvoorwaarden-handelsregistergegevens/ contact: name: Kamer van Koophandel url: https://developers.kvk.nl/nl version: '1.0' servers: - url: https://api.preprod.kvk.nl/api description: PreProd API - url: https://api.kvk.nl/api description: Productie API (alleen te gebruiken met een API key voor het opvragen van openbare data) - url: https://api-secure.kvk.nl/api description: Productie API (te gebruiken met een certificaat voor het opvragen van afgeschermde data) security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: vestigingen externalDocs: description: Voor meer informatie over deze API url: https://developers.kvk.nl/nl/support paths: /v1/vestigingen/kvknummer/{kvknummer}/vestigingsnummer/{vestigingsnummer}: get: tags: - vestigingen summary: Opvragen van een vestiging op basis van een kvknummer in combinatie met een vestigingsnummer operationId: vestigingByKvknummerAndVestigingsnummer parameters: - name: kvknummer in: path description: 'Een door de KVK toegekend uniek (identificerend) nummer: het Nederlands Kamer van Koophandel nummer' example: '12345678' required: true schema: pattern: ^[0-9]{8}$ type: string - name: vestigingsnummer in: path description: Een uniek nummer door de KVK toegekend aan een vestiging example: '123456789012' required: true schema: pattern: ^[0-9]{12}$ type: string - name: geoData in: query description: Voeg geodata toe aan het response schema: type: boolean required: false example: geoData=true responses: '200': description: Het verzoek levert een resultaat op. Als geen resultaten worden gevonden die aan de path parameter voldoen, wordt een 404 NotFound teruggegeven headers: api-version: $ref: '#/components/headers/api_version' warning: $ref: '#/components/headers/warning' content: application/json: schema: $ref: '#/components/schemas/VestigingenDto' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '406': $ref: '#/components/responses/NotAcceptable' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/DefaultError' components: securitySchemes: BearerAuth: type: http description: De JWT token dient bij elk request meegestuurd te worden. Indien deze niet juist wordt meegestuurd, of het een ongeldig token betreft, zul je de foutmelding `401 Unauthorized` terugkrijgen scheme: bearer bearerFormat: JWT ApiKeyAuth: type: apiKey description: De API-key die je hebt gekregen dient bij elke request via de `apikey` request header meegestuurd te worden. Indien deze niet juist wordt meegestuurd, of het een ongeldige key betreft, zul je de foutmelding `401 Unauthorized` terugkrijgen name: apikey in: header schemas: VestigingenDto: x-implements: - Vestigingen type: object properties: links: x-extra-annotation: '@com.fasterxml.jackson.annotation.JsonIgnore' allOf: - $ref: '#/components/schemas/LinksDto' algemeen: $ref: '#/components/schemas/AlgemeenDto' vestigingen: type: array items: properties: vestigingsnaam: description: De eerste handelsnaam van een commerciële vestiging of de naam van een niet-commerciële vestiging type: string maxLength: 625 datumAanvang: description: De datum waarop de activiteiten van een onderneming of rechtspersoon in een gebouw of complex van gebouwen zijn begonnen type: string pattern: ^[0-9]{8}$ datumEinde: description: De datum waarop de activiteiten van een onderneming of rechtspersoon in een gebouw of complex van gebouwen zijn gestaakt type: string pattern: ^[0-9]{8}$ registratieTijdstipInschrijving: description: De datum en tijdstip van de eerste registratie van een vestiging in het Handelsregister allOf: - $ref: '#/components/schemas/RegistratieTijdstipDto' registratieTijdstipUitschrijving: description: De datum en tijdstip van de registratie van opheffen van een vestiging in het Handelsregister allOf: - $ref: '#/components/schemas/RegistratieTijdstipDto' ambtshalveUitschrijving: description: Indicatie die aangeeft of de vestiging ambtshalve is opgeheven. Deze heeft altijd de waarde 'Ja' of 'Nee' allOf: - $ref: '#/components/schemas/IndicatieDto' soortVestiging: $ref: '#/components/schemas/SoortVestigingDto' soortVestigingsactiviteiten: $ref: '#/components/schemas/SoortVestigingsactiviteitenDto' activiteitenomschrijving: description: De korte bondige omschrijving van de activiteiten die de vestiging uitoefent. De beschrijving bevat de nadere aanduiding van de commerciële activiteiten (commerciële vestiging) of de nadere aanduiding van de niet-commerciële activiteiten (niet-commerciële vestiging) type: string maxLength: 2000 totaalWerkzamePersonen: description: Het totaal aantal werkzame personen bij een vestiging is de optelsom van aantal parttime en fulltime werkzame personen bij een vestiging type: integer parttimeWerkzamePersonen: description: Het aantal parttime werkzame personen bij een vestiging is het aantal natuurlijke personen dat minder dan 15 uur werkt bij een commerciële vestiging type: integer fulltimeWerkzamePersonen: description: Het aantal fulltime werkzame personen bij een vestiging is het aantal natuurlijke personen dat 15 uur of meer werkt bij een commerciële vestiging type: integer peildatumWerkzamePersonen: description: De datum waarop het aantal parttime en fulltime werkzame personen van de commerciële vestiging is geteld type: string pattern: ^[0-9]{8}$ exporteert: description: De exportindicator geeft aan of de commerciële vestiging goederen of diensten vanuit Nederland naar het buitenland uitvoert allOf: - $ref: '#/components/schemas/IndicatieDto' importeert: description: De importindicator is een indicatie of de commerciële vestiging goederen of diensten vanuit het buitenland naar Nederland invoert allOf: - $ref: '#/components/schemas/IndicatieDto' voortzettingVestiging: $ref: '#/components/schemas/VoortzettingVestigingDto' naamgevingen: $ref: '#/components/schemas/NaamgevingenDto' activiteiten: $ref: '#/components/schemas/ActiviteitenDto' communicatiegegevens: $ref: '#/components/schemas/CommunicatiegegevensDto' adres: $ref: '#/components/schemas/AdresDto' Fout: type: object properties: code: description: Foutcode type: string omschrijving: description: Omschrijving van de foutmelding type: string Error: type: object properties: fout: type: array items: $ref: '#/components/schemas/Fout' LinksDto: type: object required: - href properties: href: type: string title: type: string IndicatieDto: description: Geeft de indicatie aan van de bewering die met het attribuut wordt omschreven; J (Ja) N (Nee) O (Onbekend) type: object properties: code: type: string enum: - J - N - O omschrijving: type: string AlgemeenDto: type: object x-extra-annotation: '@com.fasterxml.jackson.annotation.JsonUnwrapped' properties: vestigingsnummer: description: Een uniek nummer door de KVK toegekend aan een vestiging type: string pattern: ^[0-9]{12}$ kvkNummer: description: 'Een door de KVK toegekend uniek (identificerend) nummer: het Nederlands Kamer van Koophandel nummer' type: string pattern: ^[0-9]{8}$ actief: description: Indicator die aangeeft of de inschrijving actief of inactief is allOf: - $ref: '#/components/schemas/IndicatieDto' SoortRegistratieTijdstipDto: description: De mogelijke waarden van het SoortRegistratieTijdstip die kunnen voorkomen; DATUMTIJDSTIP (DatumTijdstip), VASTGESTELD_ONBEKEND (Vastgesteld onbekend) type: object properties: code: type: string enum: - DATUMTIJDSTIP - VASTGESTELD_ONBEKEND omschrijving: type: string RegistratieTijdstipDto: type: object properties: soortRegistratieTijdstip: $ref: '#/components/schemas/SoortRegistratieTijdstipDto' waarde: type: string pattern: ^[0-9]{17}$ SoortVestigingDto: description: 'Geeft aan of deze vestiging een hoofdvestiging of een nevenvestiging is; Hoofdvestiging (Hoofdvestiging), Nevenvestiging (Nevenvestiging)' type: object properties: code: type: string enum: - Hoofdvestiging - Nevenvestiging omschrijving: type: string SoortVestigingsactiviteitenDto: description: Geeft aan of deze vestiging een commerciële vestiging of een niet-commerciële vestiging is; Commercieel (Commercieel), NietCommercieel (NietCommercieel) type: object properties: code: type: string enum: - Commercieel - NietCommercieel omschrijving: type: string VoortzettingVestigingDto: description: Een vestiging wordt voortgezet in een andere maatschappelijke activiteit type: array items: properties: registratieTijdstipVoortzetting: description: Het tijdstip waarop de voortzetting vestiging bij de KVK in het Handelsregister is geregistreerd allOf: - $ref: '#/components/schemas/RegistratieTijdstipDto' datumVoortzettingVestiging: description: De datum waarop de voortzetting vestiging heeft plaatsgevonden type: string pattern: ^[0-9]{8}$ SoortNaamDto: description: Geeft het soort naam van de vestiging aan; Handelsnaam (Handelsnaam), Naam (Naam), OokGenoemd (OokGenoemd), StatutaireNaam (StatutaireNaam) type: object properties: code: type: string enum: - Handelsnaam - Naam - OokGenoemd - StatutaireNaam omschrijving: type: string NaamgevingenDto: description: De namen van een vestiging type: array items: properties: naam: description: De naam die hoort bij een vestiging type: string maxLength: 625 soortNaam: $ref: '#/components/schemas/SoortNaamDto' SbiCodeDto: description: De SBI-code is een code (van maximaal 6 cijfers) voor de classificatie van activiteiten. De codering van de activiteit is conform de SBI classificatie bij CBS type: object properties: code: type: string omschrijving: type: string SoortActiviteitDto: description: Geeft aan of een activiteit een hoofdactiviteit of nevenactiviteit is van de vestiging; Hoofdactiviteit (Hoofdactiviteit), Nevenactiviteit (Nevenactiviteit) type: object properties: code: type: string enum: - Hoofdactiviteit - Nevenactiviteit omschrijving: type: string ActiviteitenDto: description: De verzameling van alle activiteiten van een vestiging. De verzameling van activiteiten van een vestiging is te relateren aan de activiteitenomschrijving van de vestiging. Activiteit bevat de SBI-code met bijbehorende omschrijving van die activiteit type: array items: properties: sbiCode: $ref: '#/components/schemas/SbiCodeDto' soortActiviteit: $ref: '#/components/schemas/SoortActiviteitDto' SoortCommunicatiegegevenDto: type: object description: Bevat de waarden telefoonnummer, emailadres (in geval van een e-mailadres) of internetadres (in geval van een website); T (Telefoonnummer), E (Emailadres), I (Internetadres) properties: code: type: string enum: - T - E - I omschrijving: type: string TelefoonnummerDto: description: Het telefoonnummer waarop de vestiging bereikbaar is type: object properties: landnummer: description: De internationale toegangscode van het land dat hoort bij het telefoonnummer type: string maxLength: 5 nummer: description: Het telefoonnummer zonder opmaak. Zowel het netnummer als het abonneenummer maken deel uit van dit nummer, zonder internationale toegangscode type: string maxLength: 15 CommunicatiegegevensDto: description: De communicatiegegevens van een vestiging type: array items: properties: soortCommunicatiegegeven: $ref: '#/components/schemas/SoortCommunicatiegegevenDto' internetadres: description: Het internetadres (WWW) waarop de vestiging via internet bereikbaar is type: string maxLength: 300 telefoonnummer: $ref: '#/components/schemas/TelefoonnummerDto' emailadres: description: Het e-mailadres waarop de vestiging per e-mail bereikbaar is type: string maxLength: 200 SoortAdresDto: description: Geeft aan welk soort adres het betreft. Het adres kan één van de volgende soorten zijn; BinnenlandsAdres (Binnenlands adres), BuitenlandsAdres (Buitenlands adres), BinnenlandsPostbusAdres (Binnenlands postbusadres), VrijeLocatie (Vrije locatie), AdresOnbekend (Adres Onbekend) type: object properties: code: type: string enum: - BinnenlandsAdres - BuitenlandsAdres - BinnenlandsPostbusAdres - VrijeLocatie - AdresOnbekend omschrijving: type: string AanduidingBijBinnenlandsAdresDto: description: De aanduiding die wordt gebruikt voor adressen die niet zijn voorzien van de gebruikelijke straatnaam en huisnummeraanduidingen; bij (Bij), tegenover (Tegenover) type: object properties: code: type: string enum: - bij - tegenover omschrijving: type: string LandDto: description: Het land waar het adres zich bevindt type: object properties: code: type: string omschrijving: type: string GeoDataDto: description: Basisregistratie Adressen en Gebouwen gegevens uit het kadaster type: object properties: gpsLatitude: description: GPS Breedtegraad type: number gpsLongitude: description: GPS Lengtegraad type: number rijksdriehoekX: description: Rijksdriehoek X-coördinaat type: number rijksdriehoekY: description: Rijksdriehoek Y-coördinaat type: number rijksdriehoekZ: description: Rijksdriehoek Z-coördinaat type: number AdresGegevensDto: type: object properties: soortAdres: $ref: '#/components/schemas/SoortAdresDto' straatnaam: description: De straat van het adres type: string maxLength: 80 straatnaamHuisnummer: description: Het gegeven straatnaam/huisnummer is een combinatie van de straatnaam en het huisnummer in het buitenland type: string maxLength: 250 aanduidingBijBinnenlandsAdres: $ref: '#/components/schemas/AanduidingBijBinnenlandsAdresDto' huisnummer: description: Het huisnummer van het adres type: integer huisletter: description: De huisletter die door de gemeente is toegekend aan het huisnummer type: string pattern: '[a-zA-Z]{1}' huisnummerToevoeging: description: Een toevoeging van het adres bijvoorbeeld rood, bis, etc. type: string maxLength: 10 postcode: description: De in Nederland gangbare postcode voor een Nederlands postadres, bestaande uit een numeriek deel en een alfabetisch deel type: string pattern: ^[0-9]{4}$|^[0-9]{4}[a-zA-Z]{2}$ maxLength: 6 postcodePlaats: description: De postcode/plaats is de combinatie van een postcode en plaats in het buitenland type: string maxLength: 250 woonplaats: description: De woonplaats van het adres betreft een door het bevoegde gemeentelijke orgaan als zodanig aangewezen en van een naam voorzien gedeelte van het grondgebied van de gemeente type: string maxLength: 80 regio: description: Regio is een deel van het land (streek, provincie, etc.) type: string maxLength: 250 land: $ref: '#/components/schemas/LandDto' identificatieAdresseerbaarObject: description: De unieke BAG identificatie van een adresseerbaar object. Een adresseerbaar object is een verblijfsobject, een standplaats of een ligplaats type: string maxLength: 16 identificatieNummeraanduiding: description: De unieke identificatie van de BAG nummeraanduiding. Een nummeraanduiding is een door het bevoegde gemeentelijke orgaan als zodanig toegekende aanduiding van een verblijfsobject, een standplaats of een ligplaats type: string maxLength: 16 toevoegingAdres: description: Vrije tekst om een adres nader aan te kunnen duiden. Het gaat hier bijvoorbeeld om bedrijfsverzamelgebouwen waarbij meerdere vestigingen op hetzelfde adres zitten en waarbij onderscheid gemaakt worden door een extra omschrijving van de locatie, bijvoorbeeld 3de verdieping kamer 315 type: string maxLength: 100 locatiebeschrijving: description: Vrije tekst wanneer er sprake is van een vrije locatie type: string maxLength: 100 geoData: $ref: '#/components/schemas/GeoDataDto' AdresDto: description: Een adres geeft een locatie aan welke kan worden bezocht of waarnaar post kan worden verzonden type: object properties: bezoekadres: description: Het adres van een vestiging waarop deze fysiek bereikbaar is allOf: - properties: bezoekadresAfgeschermd: description: Geeft aan of het bezoekadres, op basis van een afschermingsverzoek, afgeschermd is of niet allOf: - $ref: '#/components/schemas/IndicatieDto' - $ref: '#/components/schemas/AdresGegevensDto' postadres: description: Het adres van een vestiging voor correspondentie allOf: - properties: postbusnummer: description: Het nummer van een postbus dat wordt gebruikt als postadres type: integer - $ref: '#/components/schemas/AdresGegevensDto' responses: DefaultError: description: Er is een onverwachte fout opgetreden content: application/json: schema: $ref: '#/components/schemas/Error' BadRequest: description: Een opgegeven parameter is niet valide content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Geen of onjuist JWT token aangeleverd content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Niet geautoriseerd voor deze operatie content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Er zijn geen resultaten gevonden aan de hand van de opgegeven parameter(s) content: application/json: schema: $ref: '#/components/schemas/Error' NotAcceptable: description: Opgegeven Accept header wordt niet ondersteund content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Er is een interne fout opgetreden content: application/json: schema: $ref: '#/components/schemas/Error' headers: api_version: schema: type: string description: Geeft een specifieke API-versie aan in de context van een specifieke aanroep example: 1.0.0 warning: schema: type: string description: Zie RFC 7234. In het geval een major versie wordt uitgefaseerd, gebruiken we warn-code 299 ('Miscellaneous Persistent Warning') en het API end-point (inclusief versienummer) als de warn-agent van de warning, gevolgd door de warn-text met de human-readable waarschuwing example: '299 https://api.kvk.nl/api/v1/testnaam/ ''Deze versie van de API is verouderd en zal uit dienst worden genomen op 2025-02-01. Raadpleeg voor meer informatie hier de documentatie: https://developers.kvk.nl/nl/apis/testnaam''.'