openapi: 3.0.1
info:
  title: <to be completed>
  description: <to be completed>
  version: 1.3.0-CR1
servers:
- description: ''
  url: https://api.uat.btx.fr.banqup.com/entity/directorystore
- description: ''
  url: https://api.uat.btx.eu.banqup.com/entity/directorystore
paths:
  /v1/directory/{countryCode}/{companyId}:
    get:
      tags:
      - directory
      summary: Lookup company 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 company by id"
      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
      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\xE9s 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\xE9s 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\xE9s 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
                          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-27 12:34:50
                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:
      - public_directory_store: []
  /v1/directory/{countryCode}:
    get:
      tags:
      - directory
      summary: Search companies
      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/> Search companies"
      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: 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-27 12:34:50
                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:
      - public_directory_store: []
components:
  schemas:
    CompanyResponse:
      type: object
      properties:
        id:
          type: string
          description: Identifier of this entity
        names:
          type: object
          additionalProperties:
            type: string
            description: Names for this entity
          description: Names for this entity
        metadata:
          type: object
          additionalProperties:
            type: object
            description: Metadata for this entity
          description: Metadata for this entity
        addresses:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Iso20022StructuredAddress'
          description: Addresses for this entity
        globalIdentifiers:
          type: object
          additionalProperties:
            type: object
            description: Global identifiers for this entity
          description: Global identifiers for this entity
        detailUrl:
          type: string
          description: URL to follow to get full information on this entity
        spaces:
          type: array
          items:
            $ref: '#/components/schemas/CompanyResponse'
      description: List of response entities
    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
      example: be
      enum:
      - be
      - fr
    ListCompaniesResponse:
      required:
      - currentPage
      - pageSize
      type: object
      properties:
        companies:
          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
  securitySchemes:
    public_directory_store:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://docs.uat.btx.banqup.com/docs/identity/auth/get-bearer-token
          scopes:
            '': ''
        authorizationCode:
          authorizationUrl: https://api.uat.btx.fr.banqup.com/v1/oauth20/authorization
          tokenUrl: https://api.uat.btx.fr.banqup.com/v1/oauth20/token_kc
          scopes:
            '': ''
