openapi: 3.0.1
info:
  title: Naamgeving API
  description: Naamgeving informatie opvragen van een specifiek bedrijf en/of vestiging
  termsOfService: https://www.kvk.nl/over-kvk/over-het-handelsregister/toegang-handelsregister/aanvraag-toegangscode/gebruiksvoorwaarden/
  contact:
    name: Kamer van Koophandel
    url: https://developers.kvk.nl/nl
  version: 1.1.1
servers:
  - url: https://api.kvk.nl/test/api/v1
    description: Test API (uses Staat der Nederlanden Private Root CA – G1 certificate chain)
  - url: https://api.kvk.nl/api/v1
    description: Production API (uses Staat der Nederlanden Private Root CA – G1 certificate chain)
tags:
  - name: naamgeving
    externalDocs:
      description: Voor meer informatie over deze API
      url: https://developers.kvk.nl/nl/support
security:
  - ApiKeyAuth: []
paths:
  /naamgevingen/kvknummer/{kvkNummer}:
    get:
      tags:
        - naamgeving
      summary: Voor een specifiek bedrijf naamgeving informatie opvragen op basis van een kvkNummer
      operationId: naamgevingBijKvkNummer
      parameters:
        - name: kvkNummer
          in: path
          description: '__Nederlands Kamer van Koophandel nummer__: bestaat uit 8 cijfers'
          example: '59581883'
          required: true
          schema:
            pattern: ^[0-9]{8}$
            type: string
      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:
              schema: &ref_18
                type: string
                description: Geeft een specifieke API-versie aan in de context van een specifieke aanroep.
                example: 1.0.0
            warning:
              schema: &ref_19
                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/naamgevingen/ "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/naamgeving".'
          content:
            application/json:
              schema:
                type: object
                required: &ref_2
                  - kvkNummer
                properties: &ref_3
                  kvkNummer:
                    description: Nederlands Kamer van Koophandel nummer
                    example: '59581883'
                    type: string
                  rsin:
                    description: |
                      RSIN (Rechtspersonen en Samenwerkingsverbanden Informatienummer)

                      Het RSIN kan voorloopnullen bevatten
                    example: '823807071'
                    type: string
                    pattern: ^[0-9]{9}$
                  statutaireNaam:
                    description: De naam van de rechtspersoon die opgenomen is in de oprichtingsakte
                    type: string
                    example: Kamer van Koophandel
                  naam:
                    description: Naam of eerste handelsnaam van de inschrijving
                    type: string
                    example: Kamer van Koophandel
                  ookGenoemd:
                    description: Een andere naam waaronder de vereniging, stichtingen en vereniging van eigenaars ook bekend is
                    type: string
                    example: Kamer van Koophandel
                  startdatum:
                    description: |
                      In het handelsregister hebben we voor verschillende dossiers niet de exacte datums kunnen vastleggen.
                      We volgen hier de Handels Register datum vastlegging voor.
                      Hierdoor kan bij een onbekend deel van een datum nullen bevatten.
                      Bij een volledig bekende datum is het formaat YYYYMMDD ( Jaar maand dag),
                      waarbij alleen cijfers zijn toegestaan, inclusief de 0 voor onbekende delen van de datum.

                      __Mogelijke formaten van waarden__

                      | Type            | Formaat   |
                      | --------------- | --------- |
                      | Volledige datum | 20150622  |
                      | Dag onbekend    | 20150600  |
                      | Maand onbekend  | 20150012  |
                      | Datum onbekend  | 00000000  |
                    example: 20220421
                    type: string
                  einddatum:
                    description: |
                      In het handelsregister hebben we voor verschillende dossiers niet de exacte datums kunnen vastleggen.
                      We volgen hier de Handels Register datum vastlegging voor.
                      Hierdoor kan bij een onbekend deel van een datum nullen bevatten.
                      Bij een volledig bekende datum is het formaat YYYYMMDD ( Jaar maand dag),
                      waarbij alleen cijfers zijn toegestaan, inclusief de 0 voor onbekende delen van de datum.

                      __Mogelijke formaten van waarden__

                      | Type            | Formaat   |
                      | --------------- | --------- |
                      | Volledige datum | 20150622  |
                      | Dag onbekend    | 20150600  |
                      | Maand onbekend  | 20150012  |
                      | Datum onbekend  | 00000000  |
                    example: 20220421
                    type: string
                  vestigingen:
                    description: Lijst van vestigingen
                    type: array
                    items:
                      oneOf: &ref_5
                        - description: Alle namen waaronder een vestiging handelt (op volgorde van registratie)
                          type: object
                          required: &ref_6
                            - vestigingsnummer
                          properties: &ref_7
                            vestigingsnummer:
                              description: Uniek nummer dat bestaat uit 12 cijfers
                              example: '000015063097'
                              type: string
                              pattern: ^[0-9]{12}$
                            eersteHandelsnaam:
                              description: De eerste handelsnaam van de Vestiging
                              example: Kamer van Koophandel
                              type: string
                            handelsnamen:
                              description: Alle namen waaronder een onderneming of vestiging handelt
                              type: array
                              items:
                                description: Een handelsnaam is een naam waaronder een vestiging van een onderneming handelt.
                                type: object
                                properties: &ref_10
                                  naam:
                                    description: De handelsnaam van de vestiging
                                    example: Kamer van Koophandel
                                    type: string
                                  volgorde:
                                    description: Het volgorde nummer van een handelsnaam
                                    example: 0
                                    type: integer
                            _links:
                              description: URI naar API Vestigingsprofiel voor het huidige vestigingsnummer
                              type: object
                              required:
                                - vestigingsprofiel
                              properties:
                                vestigingsprofiel:
                                  required: &ref_0
                                    - href
                                  type: object
                                  properties: &ref_1
                                    href:
                                      type: string
                                    title:
                                      type: string
                                      description: Omschrijving van de link
                              example:
                                - title: Vestigingsprofiel
                                  href: https://api.kvk.nl/api/v1/vestigingsprofielen/000015063097
                        - description: De naam waaronder een niet commerciele vestiging bekend is
                          type: object
                          required: &ref_8
                            - vestigingsnummer
                          properties: &ref_9
                            vestigingsnummer:
                              description: Uniek nummer dat bestaat uit 12 cijfers
                              example: '000015063097'
                              type: string
                              pattern: ^[0-9]{12}$
                            naam:
                              description: De naam van de Vestiging
                              type: string
                            ookGenoemd:
                              description: Een andere naam waaronder de vereniging, stichtingen en vereniging van eigenaars ook bekend is
                              type: string
                            _links:
                              description: URI naar API Vestigingsprofiel voor het huidige vestigingsnummer
                              type: object
                              required:
                                - vestigingsprofiel
                              properties:
                                vestigingsprofiel:
                                  required: *ref_0
                                  type: object
                                  properties: *ref_1
                              example:
                                - title: Vestigingsprofiel
                                  href: https://api.kvk.nl/api/v1/vestigingsprofielen/000015063097
                  _links:
                    description: URI naar API Basisprofiel voor het huidige kvknummer
                    type: object
                    required:
                      - self
                      - basisprofiel
                    properties:
                      self:
                        required: *ref_0
                        type: object
                        properties: *ref_1
                      basisprofiel:
                        required: *ref_0
                        type: object
                        properties: *ref_1
                    example:
                      - title: Basisprofiel
                        href: https://api.kvk.nl/api/v1/basisprofielen/59581883
            application/hal+json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '400':
          description: Een opgegeven parameter is niet valide
          content: &ref_12
            application/hal+json:
              schema:
                type: object
                properties: &ref_4
                  fout:
                    type: array
                    items:
                      type: object
                      properties: &ref_11
                        code:
                          description: Foutcode
                          type: string
                        omschrijving:
                          description: Omschrijving van de foutmelding
                          type: string
        '401':
          description: Geen of onjuiste apikey aangeleverd
          content: &ref_13
            application/hal+json:
              schema:
                type: object
                properties: *ref_4
        '403':
          description: Niet geautoriseerd voor deze operatie
          content: &ref_14
            application/hal+json:
              schema:
                type: object
                properties: *ref_4
        '404':
          description: Er zijn geen resultaten gevonden aan de hand van de opgegeven parameter(s)
          content: &ref_15
            application/hal+json:
              schema:
                type: object
                properties: *ref_4
        '406':
          description: Opgegeven Accept header wordt niet ondersteund
          content: &ref_16
            application/hal+json:
              schema:
                type: object
                properties: *ref_4
        '500':
          description: Er is een interne fout opgetreden
          content: &ref_17
            application/hal+json:
              schema:
                type: object
                properties: *ref_4
        default:
          description: Er is een onverwachte fout opgetreden
          content:
            application/json:
              schema:
                type: object
                properties: *ref_4
            application/hal+json:
              schema:
                type: object
                properties: *ref_4
components:
  schemas:
    Naamgeving:
      type: object
      required: *ref_2
      properties: *ref_3
    Vestiging:
      oneOf: *ref_5
    CommercieleVestiging:
      description: Alle namen waaronder een vestiging handelt (op volgorde van registratie)
      type: object
      required: *ref_6
      properties: *ref_7
    NietCommercieleVestiging:
      description: De naam waaronder een niet commerciele vestiging bekend is
      type: object
      required: *ref_8
      properties: *ref_9
    Handelsnaam:
      description: Een handelsnaam is een naam waaronder een vestiging van een onderneming handelt.
      type: object
      properties: *ref_10
    Datum:
      description: |
        In het handelsregister hebben we voor verschillende dossiers niet de exacte datums kunnen vastleggen.
        We volgen hier de Handels Register datum vastlegging voor.
        Hierdoor kan bij een onbekend deel van een datum nullen bevatten.
        Bij een volledig bekende datum is het formaat YYYYMMDD ( Jaar maand dag),
        waarbij alleen cijfers zijn toegestaan, inclusief de 0 voor onbekende delen van de datum.

        __Mogelijke formaten van waarden__

        | Type            | Formaat   |
        | --------------- | --------- |
        | Volledige datum | 20150622  |
        | Dag onbekend    | 20150600  |
        | Maand onbekend  | 20150012  |
        | Datum onbekend  | 00000000  |
      example: 20220421
      type: string
    Link:
      required: *ref_0
      type: object
      properties: *ref_1
    Error:
      type: object
      properties: *ref_4
    Fout:
      type: object
      properties: *ref_11
  responses:
    BadRequest:
      description: Een opgegeven parameter is niet valide
      content: *ref_12
    Unauthorized:
      description: Geen of onjuiste apikey aangeleverd
      content: *ref_13
    Forbidden:
      description: Niet geautoriseerd voor deze operatie
      content: *ref_14
    NotFound:
      description: Er zijn geen resultaten gevonden aan de hand van de opgegeven parameter(s)
      content: *ref_15
    NotAcceptable:
      description: Opgegeven Accept header wordt niet ondersteund
      content: *ref_16
    InternalServerError:
      description: Er is een interne fout opgetreden
      content: *ref_17
  headers:
    api_version:
      schema: *ref_18
    warning:
      schema: *ref_19
  securitySchemes:
    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
