openapi: 3.0.1
info:
  title: <to be completed>
  description: <to be completed>
  version: 1.8.0
servers:
- description: ''
  url: https://api.btx.fr.banqup.com/entity/directorystore
- description: ''
  url: https://api.btx.eu.banqup.com/entity/directorystore
paths:
  /v1/directory/{countryCode}/{companyId}:
    get:
      tags:
      - directory
      summary: Lookup company by id
      description: ''
      operationId: getCompany
      parameters:
      - name: countryCode
        in: path
        description: Country code
        required: true
        schema:
          $ref: '#/components/schemas/CountryCode'
      - name: companyId
        in: path
        description: The company unique identifier.
        required: true
        schema:
          type: string
          example: 0842.217.841
      - name: language
        in: query
        description: Language/Locale in which to return names
        schema:
          type: string
      - name: headOffice
        in: query
        description: Whether to return entities with only the head office.
        schema:
          type: boolean
        example:
          value: true
      - name: include
        in: query
        description: What extra data to include in the response.
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/CompanyInclude'
        example: legalRepresentatives
      responses:
        '200':
          description: Ok. Company info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyResponse'
              examples:
                Belgian Company:
                  description: Belgian Company
                  value:
                    id: 1842.217.841
                    detailUrl: http://location/v1/directory/be/1842.217.841
                    names:
                      name: UP-last
                    metadata:
                      be:cbe:
                        id: 1842.217.841
                        type: entity
                        active: true
                        typeOfEnterprise: '2'
                        juridicalSituation: '000'
                        juridicalForm: '416'
                        startDate: 16-12-2011
                        activities:
                          FR:
                          - activityGroup: '006'
                            naceVersion: '2025'
                            naceCode: '33110'
                            classification: MAIN
                            description: Activités ONSS
                          NL:
                          - activityGroup: '006'
                            naceVersion: '2025'
                            naceCode: '33110'
                            classification: MAIN
                            description: RSZ-activiteiten
                    addresses:
                      FR:
                        country: BE
                        townName: Gent
                        addressType: BIZZ
                        streetName: Kortrijksesteenweg
                        buildingNumber: '1146'
                        postCode: '9051'
                      NL:
                        country: BE
                        townName: Gent
                        addressType: BIZZ
                        streetName: Kortrijksesteenweg
                        buildingNumber: '1146'
                        postCode: '9051'
                    globalIdentifiers:
                      be:vat: BE1842217841
                      be:startDate: 16-12-2011
                      be:entityTypeCode: '2'
                      global:tradeNumber: '1842217841'
                      be:legalCompanyType: ENTERPRISE
                      kbo:rawEnterpriseNumber: 1842.217.841
                    spaces:
                    - id: 2.341.382.733
                      names:
                        tradeName: The nxt establishment
                      addresses:
                        FR:
                          country: BE
                          townName: Kontich
                          addressType: BIZZ
                          streetName: Prins Boudewijnlaan
                          buildingNumber: 7 gebouw B
                          postBox: '101'
                          postCode: '2550'
                        NL:
                          country: BE
                          townName: Kontich
                          addressType: BIZZ
                          streetName: Prins Boudewijnlaan
                          buildingNumber: 7 gebouw B
                          postBox: '101'
                          postCode: '2550'
                      metadata:
                        be:cbe:
                          id: 2.341.382.733
                          type: establishment
                          startDate: 16-12-2011
                          activities:
                            FR:
                            - activityGroup: '006'
                              naceVersion: '2025'
                              naceCode: '33110'
                              classification: SECO
                              description: Activités ONSS
                            NL:
                            - activityGroup: '006'
                              naceVersion: '2025'
                              naceCode: '33110'
                              classification: SECO
                              description: RSZ-activiteiten
                      globalIdentifiers: {}
                    - id: 9.001.348.887
                      names:
                        branchName: some kind of branch
                      addresses:
                        FR:
                          country: TR
                          townName: yenibosna - Istamboul
                          addressType: BIZZ
                          streetName: itkib bis ticaret komplexi b/blok coban cesme
                            mekvil sanayi/caddesi
                          buildingNumber: '0'
                          postCode: '34196'
                        NL:
                          country: TR
                          townName: yenibosna - Istamboul
                          addressType: BIZZ
                          streetName: itkib bis ticaret komplexi b/blok coban cesme
                            mekvil sanayi/caddesi
                          buildingNumber: '0'
                          postCode: '34196'
                      metadata:
                        be:cbe:
                          id: 9.001.348.887
                          type: branch
                          startDate: 17-12-2011
                          activities:
                            FR:
                            - activityGroup: '006'
                              naceVersion: '2025'
                              naceCode: '33110'
                              classification: SECO
                              description: Activités ONSS
                            NL:
                            - activityGroup: '006'
                              naceVersion: '2025'
                              naceCode: '33110'
                              classification: SECO
                              description: RSZ-activiteiten
                      globalIdentifiers: {}
                French Company:
                  description: French Company
                  value:
                    id: '000325175'
                    detailUrl: http://location/v1/directory/fr/000325175
                    names:
                      name: VETEMENTS JARDI
                    metadata:
                      fr:datagouv:
                        id: '000325175'
                        type: entity
                        status: A
                        startDate: 2018-02-07
                        activities:
                          FR:
                            mainActivity: 32.12Z
                            mainActivityClassificationSystem: NAFRev2
                    globalIdentifiers:
                      fr:siren: '0200065765'
                    spaces:
                    - id: '00032517500024'
                      names:
                        tradeName: TAHITI PERLES CREATIONS
                      addresses:
                        FR:
                          country: FR
                          townName: AVIGNON
                          addressType: BIZZ
                          streetName: LEONCE DE SEYNES
                          buildingNumber: '1'
                          postCode: '84000'
                      metadata:
                        fr:datagouv:
                          id: '00032517500024'
                          type: establishment
                          headOffice: true
                          status: F
                          startDate: 2011-10-21
                          activities:
                            FR:
                              mainActivity: 47.89Z
                              mainActivityClassificationSystem: NAFRev2
                      globalIdentifiers:
                        fr:siren: '000325175'
                        fr:siret: '00032517500024'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        default:
          description: Other error messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
      security:
      - oauth2: []
  /v1/directory/{countryCode}:
    get:
      tags:
      - directory
      summary: Search companies
      description: ''
      operationId: listCompanies
      parameters:
      - name: countryCode
        in: path
        description: Country code
        required: true
        schema:
          $ref: '#/components/schemas/CountryCode'
      - name: search
        in: query
        schema:
          type: string
      - name: language
        in: query
        description: Language/Locale in which to return names
        schema:
          type: string
      - name: includeInactive
        in: query
        description: Whether to include entities with inactive status. Default value
          is false.
        schema:
          type: boolean
        example:
          value: true
      - name: headOffice
        in: query
        description: Whether to return entities with only the head office.
        schema:
          type: boolean
        example:
          value: true
      - name: page
        in: query
        description: Zero-based page index, cannot be negative, default 0
        schema:
          type: integer
          format: int32
        example: 20
      - name: pageSize
        in: query
        description: 'Page size. Minimum 1, maximum: 200, default 20'
        schema:
          type: integer
          format: int32
        example: 20
      - name: includeTotalElements
        in: query
        description: Return the totalElements number of entries in the response
        schema:
          type: boolean
        example: true
      responses:
        '200':
          description: Ok. Company info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCompaniesResponse'
              examples:
                Belgian Companies:
                  description: Belgian Companies
                  value:
                    companies:
                    - id: 1842.217.841
                      detailUrl: http://location/v1/directory/be/1842.217.841
                      names:
                        name: UP-last
                      metadata:
                        be:cbe:
                          id: 1842.217.841
                          type: entity
                          active: true
                          typeOfEnterprise: '2'
                          juridicalSituation: '000'
                          juridicalForm: '416'
                          startDate: 16-12-2011
                          activities: {}
                      addresses:
                        FR:
                          country: BE
                          townName: Gent
                          addressType: BIZZ
                          streetName: Kortrijksesteenweg
                          buildingNumber: '1146'
                          postCode: '9051'
                        NL:
                          country: BE
                          townName: Gent
                          addressType: BIZZ
                          streetName: Kortrijksesteenweg
                          buildingNumber: '1146'
                          postCode: '9051'
                      globalIdentifiers:
                        be:vat: BE1842217841
                        be:startDate: 16-12-2011
                        be:entityTypeCode: '2'
                        global:tradeNumber: '1842217841'
                        be:legalCompanyType: ENTERPRISE
                        kbo:rawEnterpriseNumber: 1842.217.841
                      spaces:
                      - id: 2.341.382.733
                        names:
                          tradeName: The nxt establishment
                        addresses:
                          FR:
                            country: BE
                            townName: Kontich
                            addressType: BIZZ
                            streetName: Prins Boudewijnlaan
                            buildingNumber: 7 gebouw B
                            postBox: '101'
                            postCode: '2550'
                          NL:
                            country: BE
                            townName: Kontich
                            addressType: BIZZ
                            streetName: Prins Boudewijnlaan
                            buildingNumber: 7 gebouw B
                            postBox: '101'
                            postCode: '2550'
                        metadata:
                          be:cbe:
                            id: 2.341.382.733
                            type: establishment
                            startDate: 16-12-2011
                            activities: {}
                        globalIdentifiers: {}
                      - id: 9.001.348.887
                        names:
                          branchName: some kind of branch
                        addresses:
                          FR:
                            country: TR
                            townName: yenibosna - Istamboul
                            addressType: BIZZ
                            streetName: itkib bis ticaret komplexi b/blok coban cesme
                              mekvil sanayi/caddesi
                            buildingNumber: '0'
                            postCode: '34196'
                          NL:
                            country: TR
                            townName: yenibosna - Istamboul
                            addressType: BIZZ
                            streetName: itkib bis ticaret komplexi b/blok coban cesme
                              mekvil sanayi/caddesi
                            buildingNumber: '0'
                            postCode: '34196'
                        metadata:
                          be:cbe:
                            id: 9.001.348.887
                            type: branch
                            startDate: 16-12-2011
                            activities: {}
                        globalIdentifiers: {}
                    totalElements: 3
                    currentPage: 0
                    pageSize: 1
                French Companies:
                  description: French Companies
                  value:
                    companies:
                    - id: '000325175'
                      names:
                        name: VETEMENTS JARDI
                      metadata:
                        fr:datagouv:
                          id: '000325175'
                          type: entity
                          status: A
                          startDate: 2018-02-07
                          activities:
                            FR:
                              mainActivity: 32.12Z
                              mainActivityClassificationSystem: NAFRev2
                      globalIdentifiers:
                        fr:siren: '0200065765'
                      detailUrl: http://location/v1/directory/fr/000325175
                      spaces:
                      - id: '00032517500024'
                        names:
                          tradeName: TAHITI PERLES CREATIONS
                        metadata:
                          fr:datagouv:
                            id: '00032517500024'
                            type: establishment
                            status: F
                            startDate: 2011-10-21
                            activities:
                              FR:
                                mainActivity: 47.89Z
                                mainActivityClassificationSystem: NAFRev2
                        addresses:
                          FR:
                            country: FR
                            townName: AVIGNON
                            addressType: BIZZ
                            streetName: LEONCE DE SEYNES
                            buildingNumber: '1'
                            postCode: '84000'
                        globalIdentifiers:
                          fr:siren: '000325175'
                          fr:siret: '00032517500024'
                    totalElements: 1
                    currentPage: 0
                    pageSize: 20
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        default:
          description: Other error messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
      security:
      - oauth2: []
  /v2/directory/{countryCode}/entities/{entityNumber}/spaces:
    get:
      tags:
      - directory
      summary: Get establishments of an entity
      description: ''
      operationId: getCompanyEstablishments
      parameters:
      - name: countryCode
        in: path
        description: Country code (e.g., 'nl' for Netherlands)
        required: true
        schema:
          $ref: '#/components/schemas/CountryCode'
      - name: entityNumber
        in: path
        description: The company unique identifier
        required: true
        schema:
          type: string
          example: '05047572'
      - name: headOffice
        in: query
        description: Filter by head office status
        schema:
          type: boolean
      - name: page
        in: query
        description: Zero-based page index, cannot be negative, default 0
        schema:
          type: integer
          format: int32
        example: 20
      - name: pageSize
        in: query
        description: 'Page size. Minimum 1, maximum: 200, default 20'
        schema:
          type: integer
          format: int32
        example: 20
      - name: includeTotalElements
        in: query
        description: Return the totalElements number of entries in the response
        schema:
          type: boolean
        example: true
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEstablishmentsResponse'
              examples:
                Netherlands Establishments:
                  description: Netherlands Establishments
                  value:
                    results:
                    - type: headOffice
                      names:
                        tradeName: Electro World Hans Brinkhuis
                      globalIdentifiers:
                        nl:kvk: '05047572'
                        nl:establishmentNumber: '000015206890'
                      address:
                        streetName: Langewijk
                        townName: Dedemsvaart
                        country: NL
                      metadata:
                        nl:kvk:
                          headOffice: true
                      parentDetailUrl: 
                        https://api.test.btx.eu.banqup.com/entity/directorystore/v2/directory/nl/entities/05047572
                      detailUrl: 
                        https://api.test.btx.eu.banqup.com/entity/directorystore/v2/directory/nl/entities/05047572/spaces/000015206890
                    - type: establishment
                      names:
                        tradeName: Expert Brinkhuis Hardenberg
                      globalIdentifiers:
                        nl:kvk: '05047572'
                        nl:establishmentNumber: '000015206904'
                      address:
                        streetName: Hulsbergenstraat
                        townName: Hardenberg
                        country: NL
                      metadata:
                        nl:kvk:
                          headOffice: false
                      parentDetailUrl: 
                        https://api.test.btx.eu.banqup.com/entity/directorystore/v2/directory/nl/entities/05047572
                      detailUrl: 
                        https://api.test.btx.eu.banqup.com/entity/directorystore/v2/directory/nl/entities/05047572/spaces/000015206904
                    currentPage: 0
                    pageSize: 10
                    totalElements: 10
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        default:
          description: Other error messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
      security:
      - oauth2: []
  /v2/directory/{countryCode}/entities/{entityNumber}:
    get:
      tags:
      - directory
      summary: Lookup entity by id
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Lookup entity by id <br/> Scope: []"
      operationId: getEntityProfile
      parameters:
      - name: countryCode
        in: path
        description: Country code (e.g., 'nl' for Netherlands)
        required: true
        schema:
          $ref: '#/components/schemas/CountryCode'
      - name: entityNumber
        in: path
        description: Entity's unique identifier.
        required: true
        schema:
          type: string
          example: '05047572'
      - name: include
        in: query
        description: What extra data to include in the response.
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/EntityInclude'
        example: headOffice
      responses:
        '200':
          description: Ok. Entity profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityProfile'
              examples:
                Netherlands Entity profile:
                  description: Netherlands Entity profile
                  value: "{\n   \"id\": \"05047572\",\n   \"names\": {\n\t \"legalName\"\
                    : \"Hans Brinkhuis\",\n\t \"tradeName\": \"Electro World Hans
                    Brinkhuis\"     // highest order\n   },\n   \"metadata\": {\n\t
                    \"nl:kvk\": {\n\t   \"startDate\": \"1993-10-05\",\n\t   \"legalForm\"\
                    : \"Vennootschap Onder Firma\",\n\t   \"extendedLegalForm\": \"\
                    Vennootschap Onder Firma\",\n\t   \"activities\": [\n\t\t {\n\t\
                    \t   \"code\": \"47404\",\n\t\t   \"description\": \"Detailhandel
                    in een algemeen assortiment van consumentenelektronica\",\n\t\t\
                    \   \"mainActivity\": true\n\t\t },\n\t\t {\n\t\t   \"code\":
                    \"33140\",\n\t\t   \"description\": \"Reparatie en onderhoud van
                    elektrische apparatuur\",\n\t\t   \"mainActivity\": false\n\t\t
                    },\n\t\t {\n\t\t   \"code\": \"47543\",\n\t\t   \"description\"\
                    : \"Detailhandel in overige elektrische huishoudelijke apparatuur\"\
                    ,\n\t\t   \"mainActivity\": false\n\t\t },\n\t\t {\n\t\t   \"\
                    code\": \"95100\",\n\t\t   \"description\": \"Reparatie en onderhoud
                    van computers en communicatieapparatuur\",\n\t\t   \"mainActivity\"\
                    : false\n\t\t },\n\t\t {\n\t\t   \"code\": \"95220\",\n\t\t  \
                    \ \"description\": \"Reparatie en onderhoud van huishoudelijke
                    apparaten en van werktuigen voor gebruik in huis en tuin\",\n\t\
                    \t   \"mainActivity\": false\n\t\t }\n\t   ],\n\t   \"tradeNames\"\
                    : [\n\t\t {\n\t\t   \"name\": \"Electro World Hans Brinkhuis\"\
                    ,\n\t\t   \"order\": 0\n\t\t }\n\t   ]\n\t }\n   },\n   \"globalIdentifiers\"\
                    : {\n\t \"nl:kvk\": \"05047572\",\n\t \"nl:rsin\": \"802248810\"\
                    \n   },\n   \"address\": {\n\t \"addressType\": \"BIZZ\",\n\t
                    \"streetName\": \"Langewijk\",\n\t \"buildingNumber\": \"406\"\
                    ,\n\t \"postCode\": \"7701AS\",\n\t \"townName\": \"Dedemsvaart\"\
                    ,\n\t \"country\": \"NL\"\n   },\n   \"detailUrl\": \"https://api.test.btx.eu.banqup.com/entity/directorystore/v2/directory/nl/entities/05047572\"\
                    ,\n   \"listSpaceUrl\": \"https://api.test.btx.eu.banqup.com/entity/directorystore/v2/directory/nl/entities/05047572/spaces\"\
                    ,\n   \"headOffice\": {\n\t \"id\": \"000015206890\",\n\t \"type\"\
                    : \"headOffice\",\n\t \"names\": {\n\t   \"tradeName\": \"Electro
                    World Hans Brinkhuis\"\n\t },\n\t \"metadata\": {\n\t   \"nl:kvk\"\
                    : {\n\t\t \"headOffice\": true,\n\t\t \"startDate\": \"1990-01-01\"\
                    ,\n\t\t \"tradeName\": [\n\t\t   {\n\t\t\t \"name\": \"Electro
                    World Hans Brinkhuis\",\n\t\t\t \"order\": 0\n\t\t   }\n\t\t ]\n\
                    \t   }\n\t },\n\t \"globalIdentifiers\": {\n\t   \"nl:kvk\": \"\
                    05047572\",\n\t   \"nl:establishmentNumber\": \"000015206890\"\
                    ,\n\t   \"global:websites\": [\n\t\t \"www.hansbrinkhuis.nl\"\n\
                    \t   ]\n\t },\n\t \"address\": {\n\t   \"addressType\": \"BIZZ\"\
                    ,\n\t   \"streetName\": \"Langewijk\",\n\t   \"buildingNumber\"\
                    : \"406\",\n\t   \"postCode\": \"7701AS\",\n\t   \"townName\"
                    : \"Dedemsvaart\",\n\t   \"country\": \"NL\"\n\t },\n\t \"parentDetailUrl\"\
                    : \"https://api.test.btx.eu.banqup.com/entity/directorystore/v2/directory/nl/entities/05047572\"\
                    ,\n\t \"detailUrl\": \"https://api.test.btx.eu.banqup.com/entity/directorystore/v2/directory/nl/entities/05047572/spaces/000015206890\"\
                    \n   }\n }\n"
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        default:
          description: Other error messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
  /v2/directory/{countryCode}/entities/{entityNumber}/spaces/{spaceNumber}:
    get:
      tags:
      - directory
      summary: Get establishment detail
      description: ''
      operationId: getEstablishmentProfile
      parameters:
      - name: countryCode
        in: path
        description: Country code
        required: true
        schema:
          $ref: '#/components/schemas/CountryCode'
      - name: entityNumber
        in: path
        description: The entity unique identifier
        required: true
        schema:
          type: string
          example: '05047572'
      - name: spaceNumber
        in: path
        description: The establishment unique identifier
        required: true
        schema:
          type: string
          example: '000000001234'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EstablishmentProfileResponse'
              examples:
                Netherlands Establishment Profile:
                  description: Netherlands Establishment Profile
                  value:
                    id: 05047572-000015206890
                    type: headOffice
                    names:
                      tradeName: Electro World Hans Brinkhuis
                    globalIdentifiers:
                      nl:kvk: '05047572'
                      nl:establishmentNumber: '000015206890'
                    address:
                      streetName: Langewijk
                      houseNumber: '75'
                      postalCode: 7701PH
                      townName: Dedemsvaart
                      country: NL
                    metadata:
                      nl:kvk:
                        headOffice: true
                    parentDetailUrl: 
                      https://api.test.btx.eu.banqup.com/entity/directorystore/v2/directory/nl/entities/05047572
                    detailUrl: 
                      https://api.test.btx.eu.banqup.com/entity/directorystore/v2/directory/nl/entities/05047572/spaces/000015206890
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        default:
          description: Other error messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
      security:
      - oauth2: []
  /v2/directory/{countryCode}:
    get:
      tags:
      - directory
      summary: Search companies V2
      description: ''
      operationId: listCompaniesV2
      parameters:
      - name: countryCode
        in: path
        description: Country code (e.g., 'nl' for Netherlands)
        required: true
        schema:
          $ref: '#/components/schemas/CountryCode'
      - name: search
        in: query
        description: Search query. Can be KVK number (8 digits), establishment number
          (12 digits), or company name
        required: true
        schema:
          type: string
      - name: includeInactive
        in: query
        description: Include inactive registrations
        schema:
          type: boolean
        example:
          value: false
      - name: type
        in: query
        description: Type of entity to filter by
        schema:
          type: string
          description: Type of entity
          enum:
          - legalEntity
          - headOffice
          - establishment
      - name: page
        in: query
        description: Zero-based page index, cannot be negative, default 0
        schema:
          type: integer
          format: int32
        example: 20
      - name: pageSize
        in: query
        description: 'Page size. Minimum 1, maximum: 200, default 20'
        schema:
          type: integer
          format: int32
        example: 20
      - name: includeTotalElements
        in: query
        description: Return the totalElements number of entries in the response
        schema:
          type: boolean
        example: true
      responses:
        '200':
          description: Ok. Directory search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCompaniesResponse'
              examples:
                Search Results:
                  description: Search Results
                  value:
                    results:
                    - type: legalEntity
                      names:
                        legalName: Cees & Hans
                      globalIdentifiers:
                        nl:kvk: '27363079'
                      detailUrl: 
                        https://api.test.btx.eu.banqup.com/entity/directorystore/v2/directory/nl/entities/27363079
                    - type: headOffice
                      names:
                        tradeName: Electro World Hans Brinkhuis
                      globalIdentifiers:
                        nl:kvk: '05047572'
                        nl:establishmentNumber: '000015206890'
                      address:
                        streetName: Langewijk
                        townName: Dedemsvaart
                        country: NL
                      parentDetailUrl: 
                        https://api.test.btx.eu.banqup.com/entity/directorystore/v2/directory/nl/entities/05047572
                      detailUrl: 
                        https://api.test.btx.eu.banqup.com/entity/directorystore/v2/directory/nl/entities/05047572/spaces/000015206890
                    - type: establishment
                      names:
                        tradeName: Hans Kalf Intercoiffure
                      globalIdentifiers:
                        nl:kvk: '05010111'
                        nl:establishmentNumber: '000001081047'
                      address:
                        streetName: Dobbe
                        townName: Zwolle
                        country: NL
                      parentDetailUrl: 
                        https://api.test.btx.eu.banqup.com/entity/directorystore/v2/directory/nl/entities/05010111
                      detailUrl: 
                        https://api.test.btx.eu.banqup.com/entity/directorystore/v2/directory/nl/entities/05010111/spaces/000001081047
                    currentPage: 0
                    pageSize: 10
                    totalElements: 5167
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        default:
          description: Other error messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
      security:
      - oauth2: []
components:
  schemas:
    CompanyResponse:
      type: object
      properties:
        type:
          type: string
          description: Type of entity
          enum:
          - legalEntity
          - headOffice
          - establishment
        names:
          $ref: '#/components/schemas/CompanyNames'
        globalIdentifiers:
          type: object
          additionalProperties:
            type: object
            description: Global identifiers for the entity
          description: Global identifiers for the entity
        address:
          $ref: '#/components/schemas/CompanyAddress'
        parentDetailUrl:
          type: string
          description: URL to get full details of the parent legal entity
        detailUrl:
          type: string
          description: URL to get full details of this entity
      description: List of entities or establishments
    Iso20022StructuredAddress:
      required:
      - country
      - townName
      type: object
      properties:
        country:
          type: string
          description: Nation with its own government, expressed as a two letter ISO
            3166 code (alpha-2) of the country. The country code is written in upper
            case.
          example: BE
        townName:
          type: string
          description: Name of a built-up area, with defined boundaries, and a local
            government.
          example: La Hulpe
        addressType:
          type: string
          description: Identifies the nature of the postal address.
          example: ADDR
          enum:
          - ADDR
          - PBOX
          - HOME
          - BIZZ
          - MLTO
          - DLVY
        streetName:
          maxLength: 140
          type: string
          description: Name of a street or thoroughfare.
          example: Avenue Reine Astrid
        buildingNumber:
          maxLength: 16
          type: string
          description: A unique number assigned to the building in the street or area
            //Number that identifies the position of a building on a street.
          example: '40'
        careOf:
          maxLength: 140
          type: string
          description: Identifies an addressee that is accepting the correspondence
            for the intended recipient. Using care of ensures the correspondence reaches
            the right recipient rather than getting returned to the sender.
          example: Finance
        department:
          maxLength: 70
          type: string
          description: Identification of a division of a large organisation or building.
          example: Finance
        subDepartment:
          maxLength: 70
          type: string
          description: Identification of a sub-division of a large organisation or
            building.
          example: Accounting
        buildingName:
          maxLength: 140
          type: string
          description: Name of the building or house.
          example: Empire State Building
        floor:
          maxLength: 70
          type: string
          description: Floor or storey within a building.
          example: ground
        unitNumber:
          maxLength: 16
          type: string
          description: Identifies a flat or dwelling within the building.
          example: '2'
        postBox:
          maxLength: 16
          type: string
          description: Numbered box in a post office, assigned to a person or organisation,
            where letters are kept until called for.
          example: '1003'
        room:
          maxLength: 70
          type: string
          description: Building room number.
          example: '2.22'
        postCode:
          maxLength: 16
          type: string
          description: Identifier consisting of a group of letters and/or numbers
            that is added to a postal address to assist the sorting of mail.
          example: '1310'
        townLocationName:
          maxLength: 140
          type: string
          description: Specific location name within the town. eg Borough (USA), Village
            (GB).
          example: Miami Beach
        districtName:
          maxLength: 140
          type: string
          description: Identifies a subdivision within a country sub-division eg County
            (USA), Landkreis (DE).
          example: Miami-Dade, Coburg
        countrySubDivision:
          maxLength: 35
          type: string
          description: Identifies a subdivision of a country such as state (USA),
            Bundesland (DE), region, province,....
          example: Florida, Bayern, Wallonia, Hainaut
      description: Information that locates and identifies a specific address, as
        defined by postal services
      externalDocs:
        description: More about EPC Interbank Structured Address Structure; see also
          PostalAddress27 type in https://www.iso20022.org/message/22905/download
        url: 
          https://www.europeanpaymentscouncil.eu/sites/default/files/kb/file/2022-10/EPC153-22%20EPC%20guidance%20document%20-%20Use%20of%20Structured%20Address%20under%20the%20SEPA%20Payment%20Schemes%20as%20of%20Nov%202025.pdf
    ApiErrorProblemDetail:
      required:
      - error
      - requestId
      - timestamp
      type: object
      properties:
        status:
          type: integer
          format: int32
        error:
          type: string
        requestId:
          type: string
        timestamp:
          type: string
          format: date-time
        type:
          type: string
          format: uri
        title:
          type: string
        detail:
          type: string
        instance:
          type: string
          format: uri
        problems:
          type: array
          items:
            $ref: '#/components/schemas/NestedProblem'
        properties:
          type: object
          additionalProperties:
            type: object
    NestedProblem:
      required:
      - detail
      - error
      - title
      type: object
      properties:
        error:
          type: string
        title:
          type: string
        detail:
          type: string
        type:
          type: string
          format: uri
    CountryCode:
      type: string
      description: The supported country codes for V2
      example: nl
      enum:
      - nl
    CompanyInclude:
      type: string
      description: The supported include param value
      example: legalRepresentatives
      enum:
      - legalRepresentatives
    ListCompaniesResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/CompanyResponse'
        totalElements:
          type: integer
          description: Total number of items in the database that correspond to this
            search criteria
          format: int64
        currentPage:
          type: integer
          description: Current page
          format: int32
        pageSize:
          type: integer
          description: Response page size
          format: int32
    CompanyAddress:
      type: object
      properties:
        streetName:
          type: string
          description: Street name
        townName:
          type: string
          description: Town/city name
        country:
          type: string
          description: Country code (ISO 3166-1 alpha-2)
        postCode:
          type: string
          description: Postal code
        addressType:
          type: string
          description: Address type
          enum:
          - ADDR
          - PBOX
          - HOME
          - BIZZ
          - MLTO
          - DLVY
        buildingNumber:
          type: string
          description: Building number
      description: Address of the entity
    CompanyNames:
      type: object
      properties:
        legalName:
          type: string
          description: Legal name of the entity
        tradeName:
          type: string
          description: Trade name of the establishment
      description: Names of the entity
    EstablishmentResponse:
      type: object
      properties:
        type:
          type: string
          description: Type of entity
          enum:
          - legalEntity
          - headOffice
          - establishment
        names:
          $ref: '#/components/schemas/CompanyNames'
        globalIdentifiers:
          type: object
          additionalProperties:
            type: object
            description: Global identifiers for the entity
          description: Global identifiers for the entity
        address:
          $ref: '#/components/schemas/CompanyAddress'
        parentDetailUrl:
          type: string
          description: URL to get full details of the parent legal entity
        detailUrl:
          type: string
          description: URL to get full details of this entity
        metadata:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: object
              description: Metadata of entity or establishment
            description: Metadata of entity or establishment
          description: Metadata of entity or establishment
      description: List of establishments
    ListEstablishmentsResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/EstablishmentResponse'
        totalElements:
          type: integer
          description: Total number of items in the database that correspond to this
            search criteria
          format: int64
        currentPage:
          type: integer
          description: Current page
          format: int32
        pageSize:
          type: integer
          description: Response page size
          format: int32
    EntityProfile:
      type: object
      properties:
        id:
          type: string
          description: Id of the entity
        names:
          $ref: '#/components/schemas/CompanyNames'
        metadata:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: object
              description: Metadata of entity
            description: Metadata of entity
          description: Metadata of entity
        globalIdentifiers:
          type: object
          additionalProperties:
            type: string
            description: Global identifiers for the entity
          description: Global identifiers for the entity
        address:
          $ref: '#/components/schemas/CompanyAddress'
        detailUrl:
          type: string
          description: URL to get full details of this entity
        listSpaceUrl:
          type: string
          description: URL to get the establishments of this entity
        headOffice:
          $ref: '#/components/schemas/HeadOffice'
    HeadOffice:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          description: Type of the establishment
        names:
          type: object
          additionalProperties:
            type: string
            description: Names of the establishment
          description: Names of the establishment
        metadata:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: object
              description: Metadata of the establishment
            description: Metadata of the establishment
          description: Metadata of the establishment
        globalIdentifiers:
          type: object
          additionalProperties:
            type: object
            description: Global identifiers for the establishment
          description: Global identifiers for the establishment
        address:
          $ref: '#/components/schemas/CompanyAddress'
        detailUrl:
          type: string
          description: URL to get full details of this establishment
        parentDetailUrl:
          type: string
          description: URL to get full details of the parent entity
      description: Head office of the entity
    EntityInclude:
      type: string
      description: The supported include param value
      example: headOffice
      enum:
      - headOffice
    EstablishmentProfileResponse:
      type: object
      properties:
        type:
          type: string
          description: Type of entity
          enum:
          - legalEntity
          - headOffice
          - establishment
        names:
          $ref: '#/components/schemas/CompanyNames'
        globalIdentifiers:
          type: object
          additionalProperties:
            type: object
            description: Global identifiers for the entity
          description: Global identifiers for the entity
        address:
          $ref: '#/components/schemas/CompanyAddress'
        parentDetailUrl:
          type: string
          description: URL to get full details of the parent legal entity
        detailUrl:
          type: string
          description: URL to get full details of this entity
        metadata:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: object
              description: Metadata of entity or establishment
            description: Metadata of entity or establishment
          description: Metadata of entity or establishment
        id:
          type: string
          description: id of the entity
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.btx.fr.banqup.com/oauth2/client_credential/gettoken
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
        authorizationCode:
          authorizationUrl: https://api.btx.fr.banqup.com/oauth2/auth
          tokenUrl: https://api.btx.fr.banqup.com/oauth2/token
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
