openapi: '3.0.3'
info:
  title: 'IWG endpoints - IV/EV/RB qualified persons API'
  description: |
    Offers a collection of public API endpoints that can be used to obtain IV/EV/RB qualified person(s).

    The following acronyms are used:
    *IV* - qualified person in insolvency (DE: 'Insolvenzverwalter'),
    *EV* - administrator in execution proceedings (DE: 'Verwalter in Exekutionssachen'),
    *RB* - restructuring officer (DE: 'Restrukturierungsbeauftragter')
  version: '1.0'
  termsOfService: https://justizonline.gv.at/jop/web/iwg/terms
  contact:
    name: Bundesministerium für Justiz
    url: https://justizonline.gv.at
    email: justizonline-iwg@brz.gv.at

servers:
  - url: https://justizonline.gv.at/jop/api/
    description: Production Server

paths:
  /v1/qualified-persons/iv:
    get:
      tags:
        - qualified-persons
      description: "Get a list of (possibly filtered if params used) qualified persons in insolvency (IV)."
      operationId: listIvQualifiedPersonsV1
      parameters:
        - $ref: '#/components/parameters/QualifiedPersonsFilterFromParam'
        - $ref: '#/components/parameters/QualifiedPersonsFilterUntilParam'
      responses:
        '200':
          description: 'List of qualified persons in insolvency'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IvQualifiedPersons'
  /v1/qualified-persons/ev:
    get:
      tags:
        - qualified-persons
      description: "Get a list of (possibly filtered if params used) administrator in execution proceedings (DE: 'Verwalter in Exekutionssachen')"
      operationId: listEvQualifiedPersonsV1
      parameters:
        - $ref: '#/components/parameters/QualifiedPersonsFilterFromParam'
        - $ref: '#/components/parameters/QualifiedPersonsFilterUntilParam'
      responses:
        '200':
          description: 'List of EV qualified persons'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvQualifiedPersons'
  /v1/qualified-persons/rb:
    get:
      tags:
        - qualified-persons
      description: "Get a list of (possibly filtered if params used) restructuring officer (DE: 'Restrukturierungsbeauftragter')"
      operationId: listRbQualifiedPersonsV1
      parameters:
        - $ref: '#/components/parameters/QualifiedPersonsFilterFromParam'
        - $ref: '#/components/parameters/QualifiedPersonsFilterUntilParam'
      responses:
        '200':
          description: 'List of RB qualified persons'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RbQualifiedPersons'
  /v1/qualified-persons/iv/{addressCode}:
    get:
      tags:
        - qualified-persons
      description: "Get a specific insolvency expert (DE: 'Insolvenzverwalter') by the qualified person's `addressCode` (i.e. ID)"
      operationId: getIvQualifiedPersonByAddressCodeV1
      parameters:
        - $ref: '#/components/parameters/IvEvRbAddressCodePathParam'
      responses:
        '200':
          description: 'The specific IV qualified person corresponding to the given path parameter `addressCode` (acting as the ID)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IvQualifiedPerson'
  /v1/qualified-persons/ev/{addressCode}:
    get:
      tags:
        - qualified-persons
      description: "Get a specific administrator in execution proceedings (DE: 'Verwalter in Exekutionssachen') by the qualified person's `addressCode` (i.e. ID)"
      operationId: getEvQualifiedPersonByAddressCodeV1
      parameters:
        - $ref: '#/components/parameters/IvEvRbAddressCodePathParam'
      responses:
        '200':
          description: 'The specific EV qualified person corresponding to the given path parameter `addressCode` (acting as the ID)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvQualifiedPerson'
  /v1/qualified-persons/rb/{addressCode}:
    get:
      tags:
        - qualified-persons
      description: "Get a specific restructuring officer (DE: 'Restrukturierungsbeauftragter') by the qualified person's `addressCode` (i.e. ID)"
      operationId: getRbQualifiedPersonByAddressCodeV1
      parameters:
        - $ref: '#/components/parameters/IvEvRbAddressCodePathParam'
      responses:
        '200':
          description: 'The specific RB qualified person corresponding to the given path parameter `addressCode` (acting as the ID)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RbQualifiedPerson'
components:
  schemas:
    FederalStates:
      type: string
      description: |
        Enum values:

        - A = complete federal area
        - 0 = Wien
        - 1 = Niederoesterreich
        - 2 = Burgenland
        - 3 = Oberoesterreich
        - 4 = Salzburg
        - 5 = Steiermark
        - 6 = Kaernten
        - 7 = Tirol
        - 8 = Vorarlberg
      enum:
        - A
        - 0
        - 1
        - 2
        - 3
        - 4
        - 5
        - 6
        - 7
        - 8
    IndustryKnowledge:
      type: string
      description: |
        Format: `<sector name>|<enum name>`

        - Construction Industry|BAU
        - Mining/Energy|ENERGIE
        - Chemicals/Pharmaceuticals/Plastics|CHEMIE
        - Electrical Installations|ELEKTRO
        - Electronic Data Processing|EDV
        - Leisure Industry|FREIZEIT
        - Hospitality Industry|GASTRO
        - Finance/Insurance/Business|GELD
        - Glass/Ceramics|GLAS
        - Woodworking/Furniture|HOLZ
        - Real Estate|IMMO
        - Agriculture/Forestry|LAND-FORST
        - Food/Beverages|LEBENSM
        - Machinery/Metals|METALL
        - Paper/Printing/Publishing|PAPIER-DRUCK
        - Other Services|SONST-DIENST
        - Textile/Leder Industry|TEXTIL
        - Transportation/Vehicles|KFZ
        - Watches/Jewelry/Photography/Optics|UHREN-FOTO
        - Company-related Services|UNT-DIENST
        - Transport/Communication|VERKEHR
        - Other|SONST
      enum:
        - BAU
        - ENERGIE
        - CHEMIE
        - ELEKTRO
        - EDV
        - FREIZEIT
        - GASTRO
        - GELD
        - GLAS
        - HOLZ
        - IMMO
        - LAND-FORST
        - LEBENSM
        - METALL
        - PAPIER-DRUCK
        - SONST-DIENST
        - TEXTIL
        - KFZ
        - UHREN-FOTO
        - UNT-DIENST
        - VERKEHR
        - SONST
    PropertyKnowledge:
      type: string
      description: |
        Enum values:

        - ALL
        - MH = 'Rented Houses' => DE: 'Miethaeuser'
        - LW = 'Agriculture and Forestry Properties' => DE: 'Liegenschaften'
      enum:
        - ALL
        - MH
        - LW
    MqxContactInfos:
      type: object
      required:
        - postalCode
        - city
        - primaryPhoneNumber
        - email
      properties:
        address:
          type: string
          description: 'Full address consisting of street name, house number, staircase number and door number'
          example: 'Sakura street 7/2/12'
        addressCode:
          type: string
          description: 'The so-called `address code` of the qualified person which uniquely identifies this particular IV/EV/RB qualified person'
          readOnly: true
          pattern: '[MQX]{1}[0-9]{6}'
        postalCode:
          type: string
          description: 'Postal code'
          example: 1030
        city:
          type: string
          description: "Name of the city (DE: 'Ort')"
          example: 'Wien'
        primaryPhoneNumber:
          type: string
          description: 'Primary telephone number'
          maxLength: 40
          example: '+436763331289'
        secondaryPhoneNumber:
          type: string
          description: 'Secondary telephone number'
          maxLength: 40
          example: '+436763331289'
        fax:
          type: string
          description: 'Fax'
          maxLength: 40
          example: '+436763331289'
        email:
          type: string
          description: 'E-Mail address'
          maxLength: 250
          pattern: '^(?:[a-zA-Z0-9!#$%&''*+/=?^_{|}~-]+(?:\.[a-zA-Z0-9!#$%&''*+/=?^_{|}~-]+)*)@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?)$'
          example: 'something@fakemail.com'
        additionalInfo:
          type: string
          description: 'Additional information'
    IvEvRbCommon:
      type: object
      description: 'The common properties for any of the IV/EV/RB qualified person objects'
      allOf:
        - $ref: '#/components/schemas/MqxContactInfos'
        - type: object
          required:
            - education
            - professionalCareer
            - jobList
            - businessKnowledge
            - employeeCount
            - judicialEmployees
            - businessAdminEmployees
            - experiencedEmployees
            - usedComputerPrograms
            - liabilityInsurance
            - handledProceduresExperience
            - representative
            - partners
          properties:
            displayName:
              type: string
              description: >
                A (possibly) full name of the current qualified persons which may contains the first, middle
                and last name,(if any) academic titles (BSc, MSc, etc).
              example: 'Mag. Daniel Bailey, BSc'
            firstName:
              minLength: 2
              type: string
              description: "First name of the qualified person"
              example: "Max"
            lastName:
              minLength: 2
              type: string
              description: "Last name of the qualified person"
              example: "Mustermann"
            nameAffix:
              type: string
              description: "Name supplement"
            academicTitlePreceding:
              type: string
              description: "The academic title(s) that is/are written in front of the name"
              example: "Dr"
            academicTitleAfter:
              type: string
              description: "The academic title(s) that is/are written after the name"
              example: "MSc"
            listType:
              type: string
              description: "The type of list the expert belongs to. For example a qualified person in insolvency has the list type IV."
              enum:
                - IV
                - EV
                - RB
            companyName:
              type: string
              description: "The name of a juristic person"
              example: "Top IT GmbH"
            job:
              type: string
              description: "The job/occupation of the IV/EV/RB qualified person (DE: 'Beruf')"
              example: "lawyer (DE: 'Rechtsanwalt')"
            federalState:
              description: "The federal state in which the qualified person acts within (DE: 'Bundesland (Wirkungsbereich)')"
              type: array
              items:
                $ref: '#/components/schemas/FederalStates'
            industryKnowledge:
              description: "A string of extraordinary/special industrial knowledge this qualified person has got (DE: 'Besondere Branchenkenntnisse')."
              type: array
              items:
                $ref: '#/components/schemas/IndustryKnowledge'
              maxItems: 5
            education:
              type: string
              description: "Info about the education of the IV/EV/RB qualified person (DE: 'Ausbildung')"
            professionalCareer:
              type: string
              description: "Info about the qualified person's carrer path (DE: 'Berufliche Laufbahn')"
            jobList:
              type: string
              description: "Information about registration in a job list OR type of professional experience (DE: 'Eingetragen in eine Berufsliste oder Art der Berufserfahrung')"
            businessKnowledge:
              type: string
              description: "Information about the Business Knowledge in regards to private and commercial law (DE: 'Besondere Fachkenntnisse (in wirtschaftlichen Belangen)/Besondere Fachkenntnisse des Restrukturierungsrechts, des Wirtschaftsrechts und der Betriebswirtschaft')"
            employeeCount:
              type: string
              description: "Information about existing employees. Does not necessarily have to be just a number. This may just as well contain lines of text
                mentioning how many employees are in some specific department or similar (DE:'Mitarbeiter:innenzahl')"
            judicialEmployees:
              description: "Employees that have an education in the field of the Law (DE: 'Mitarbeiter:innen mit juristischer Ausbildung')"
              type: string
            businessAdminEmployees:
              description: "Employees that have an education in the field of Business Administration (DE: 'Mitarbeiter:innen mit betriebswirtschaftlicher Ausbildung')"
              type: string
            experiencedEmployees:
              description: "Employees that have an experience in either insolvency procedures, execution matters or restructuring procedures."
              type: string
            usedComputerPrograms:
              description: "Employees with suitable computer program knowledge. A computer program that this particular qualified person has used so far such as for example tools that
                are used to aid in handling matters (DE: 'EDV-Insolvenz-Program' )"
              example: "'Advokat' or 'WinCaus'"
            liabilityInsurance:
              description: "(DE: 'Haftpflichtversicherung')"
              type: string
              example: 'lawyer'
            handledProceduresExperience:
              type: string
              description: "Examples of previously completed procedures (number of orders since/per year, company size, employees, turnover, duration of continued operation)
              (DE: Beispiele für bisher abgewickelte Insolvenzverfahren (Anzahl der Bestellungen seit/pro Jahr, Betriebsgröße, Mitarbeiter, Umsatz, Fortbetriebsdauer)/Erfahrung als Verwalter:in in Exekutionssachen, insbesondere Anzahl der Bestellungen sowie Umsatz und Mitarbeiterzahl/
              Erfahrung als Restrukturierungsbeauftragte:r, insbesondere die Anzahl der Bestellungen sowie den Umsatz und die Mitarbeiteranzahl der Unternehmen im Restrukturierungsverfahren)"
            representative:
              description: "Representation in the exercise of administration in execution matters (DE: Vertretung bei der Ausübung der Insolvenzverwaltung/Vertretung bei der Ausübung der Verwaltung in Exekutionssachen samt Angaben nach Z 1 bis 6)/
              Vertretung bei der Besorgung der Aufgaben des/der Restrukturierungsbeauftragten samt Angaben nach lit. a bis h)."
              type: string
            partners:
              description: "Partner(s) and economically involved parties (DE: 'Gesellschaft(er) und wirtschaftlich Beteiligte')"
              type: string
    IvQualifiedPerson:
      type: object
      description: "A Insolvency Expert"
      allOf:
        - $ref: '#/components/schemas/IvEvRbCommon'
    EvQualifiedPerson:
      type: object
      description: 'Administrator in execution proceedings'
      allOf:
        - $ref: '#/components/schemas/IvEvRbCommon'
        - type: object
          required:
            - evListType
          properties:
            propertyKnowledge:
              description: "A string of extraordinary/special property-related knowledge this qualified person has got. (DE: 'Liegenschaften')"
              type: array
              items:
                $ref: '#/components/schemas/PropertyKnowledge'
            evListType:
              type: array
              description: |
                Possible enum values and their meaning:

                - EV = Execution Administrator (DE: 'Verwalter in Exekutionssachen')
                - ZV = Compulsory Administrator (DE: 'Zwangsverwalter')
              items:
                type: string
                enum:
                  - EV
                  - ZV
              maxItems: 2
    RbQualifiedPerson:
      type: object
      description: "Restructuring officer (DE: 'Restrukturierungsbeauftragter)"
      allOf:
        - $ref: '#/components/schemas/IvEvRbCommon'
        - type: object
          properties:
            registeredInJobListSince:
              type: string
              description: 'Date of registration in expert list'
              format: date
            typeOfJobExperience:
              description: 'Description of the kind of relevant experience'
              type: string
    IvQualifiedPersons:
      description: 'List of IV qualified persons'
      type: array
      items:
        $ref: '#/components/schemas/IvQualifiedPerson'
    EvQualifiedPersons:
      description: 'List of EV qualified persons'
      type: array
      items:
        $ref: '#/components/schemas/EvQualifiedPerson'
    RbQualifiedPersons:
      description: 'List of RB qualified persons'
      type: array
      items:
        $ref: '#/components/schemas/RbQualifiedPerson'
  parameters:
    QualifiedPersonsFilterFromParam:
      name: from
      in: query
      description: Filter param used to include IV/EV/RB qualified persons that have last been changed since the `from` date
      example: 2023-01-31
      required: false
      style: form
      explode: true
      schema:
        type: string
        format: date
    QualifiedPersonsFilterUntilParam:
      name: until
      in: query
      description: Filter param used to include IV/EV/RB qualified persons that have been changed up to the `until` date
      example: 2023-01-31
      required: false
      style: form
      explode: true
      schema:
        type: string
        format: date
    IvEvRbAddressCodePathParam:
      name: addressCode
      in: path
      description: "The qualified persons unique address code (which acts as the ID)"
      required: true
      style: simple
      explode: false
      schema:
        type: string
        pattern: '[MQX]{1}[0-9]{6}'

  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: X-Api-Key
      description: "For the purpose of authorization, the API key must be sent with the call"

security:
  - api_key: [ ]