openapi: 3.1.1
info:
  title: HOA API
  version: ''
  contact:
    email: servicedesk@twinq.nl
  description: >-
    Retrieving data regarding the HOA, for example information about the board
    members, committee members or the management team.
servers:
  - url: https://api.twinq.nl/hoas
    description: Production environment
paths:
  /hoas/v1/{company_id}:
    parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/next_token'
      - $ref: '#/components/parameters/max_rows'
    get:
      operationId: getHoasV1
      summary: List HOAs
      description: >-
        Returns details about the HOAs of the given TwinQ customer, such as
        Chamber of Commerce number (KVK) and Global Location Number (GLN). The
        hoa_id can then be used to call other HOA endpoints and retrieve more
        specific information.<br><br>With query parameters you can search for a
        specific HOA, for example based on a KVK number or GLN.
      security:
        - oauth2_client_credentials: []
      parameters:
        - $ref: '#/components/parameters/gln'
        - $ref: '#/components/parameters/kvk'
        - $ref: '#/components/parameters/hoa_code'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Contains the response data
                    type: array
                    items:
                      type: object
                      properties:
                        hoa_id:
                          $ref: '#/components/schemas/hoa_id'
                        naam:
                          $ref: '#/components/schemas/hoa_naam'
                        vve_code:
                          $ref: '#/components/schemas/hoa_code'
                        kvk:
                          $ref: '#/components/schemas/kvk'
                        gln:
                          $ref: '#/components/schemas/gln'
                  count:
                    $ref: '#/components/schemas/count'
                  next_token:
                    $ref: '#/components/schemas/next_token'
                  filters:
                    description: Parameters used
                    type: object
                    properties:
                      max_rows:
                        $ref: '#/components/schemas/max_rows'
                      next_token:
                        $ref: '#/components/schemas/next_token'
                      company_id:
                        $ref: '#/components/schemas/company_id'
                      kvk:
                        $ref: '#/components/schemas/kvk'
                      gln:
                        $ref: '#/components/schemas/gln'
                      hoa_code:
                        $ref: '#/components/schemas/hoa_code'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validation_error_parameters'
              examples:
                company_id:
                  $ref: '#/components/examples/company_id'
        '403':
          $ref: '#/components/responses/403'
  /hoas/v1/{company_id}/{hoa_id}/board:
    parameters:
      - $ref: '#/components/parameters/as_of_date'
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/next_token'
      - $ref: '#/components/parameters/max_rows'
      - $ref: '#/components/parameters/hoa_id'
    get:
      operationId: getBoardV1
      summary: List board members
      description: >-
        Returns details about the board members of the given HOA, i.e. role,
        name and contact details.
      security:
        - oauth2_client_credentials: []
      parameters:
        - $ref: '#/components/parameters/as_of_date'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Contains the response data
                    type: array
                    items:
                      type: object
                      properties:
                        board_member_id:
                          type: integer
                          example: 123456
                        bestuursfunctie:
                          type: string
                          example: Bestuurslid communicatie
                        bestuurslid:
                          $ref: '#/components/schemas/relatie_naam'
                        telefoonnummers:
                          $ref: '#/components/schemas/telefoonnummers'
                        e_mailadressen:
                          $ref: '#/components/schemas/e_mailadressen'
                        adres:
                          $ref: '#/components/schemas/adres'
                        postadres:
                          $ref: '#/components/schemas/postadres'
                  count:
                    $ref: '#/components/schemas/count'
                  next_token:
                    $ref: '#/components/schemas/next_token'
                  filters:
                    description: Parameters used
                    type: object
                    properties:
                      max_rows:
                        $ref: '#/components/schemas/max_rows'
                      next_token:
                        $ref: '#/components/schemas/next_token'
                      company_id:
                        $ref: '#/components/schemas/company_id'
                      hoa_id:
                        $ref: '#/components/schemas/hoa_id'
                      as_of_date:
                        $ref: '#/components/schemas/as_of_date'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
  /hoas/v1/{company_id}/{hoa_id}/committees:
    parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/next_token'
      - $ref: '#/components/parameters/max_rows'
      - $ref: '#/components/parameters/hoa_id'
    get:
      operationId: getCommitteesV1
      summary: List committee members
      description: Returns details about the committee members of the given HOA
      security:
        - oauth2_client_credentials: []
      parameters:
        - $ref: '#/components/parameters/as_of_date'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Contains the response data
                    type: array
                    items:
                      type: object
                      properties:
                        committee_member_id:
                          type: integer
                          example: 123456
                        commissie:
                          type: string
                          example: Bestuurscommissie
                        commissielid:
                          $ref: '#/components/schemas/relatie_naam'
                        telefoonnummers:
                          $ref: '#/components/schemas/telefoonnummers'
                        e_mailadressen:
                          $ref: '#/components/schemas/e_mailadressen'
                        adres:
                          $ref: '#/components/schemas/adres'
                        postadres:
                          $ref: '#/components/schemas/postadres'
                  count:
                    $ref: '#/components/schemas/count'
                  next_token:
                    $ref: '#/components/schemas/next_token'
                  filters:
                    description: Parameters used
                    type: object
                    properties:
                      max_rows:
                        $ref: '#/components/schemas/max_rows'
                      next_token:
                        $ref: '#/components/schemas/next_token'
                      company_id:
                        $ref: '#/components/schemas/company_id'
                      hoa_id:
                        $ref: '#/components/schemas/hoa_id'
                      as_of_date:
                        $ref: '#/components/schemas/as_of_date'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
  /hoas/v1/{company_id}/{hoa_id}/management-team:
    parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/hoa_id'
      - $ref: '#/components/parameters/next_token'
      - $ref: '#/components/parameters/max_rows'
    get:
      operationId: getManagementTeamV1
      summary: List management team members
      description: Returns details about the management team members of the given HOA
      security:
        - oauth2_client_credentials: []
      parameters:
        - $ref: '#/components/parameters/as_of_date'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Contains the response data
                    type: array
                    items:
                      type: object
                      properties:
                        management_team_member_id:
                          type: integer
                          example: 123456
                        rol:
                          type: string
                          example: 0. VvE-beheerder / Accountmanager
                        naam:
                          $ref: '#/components/schemas/relatie_naam'
                        functie:
                          type: string
                          example: Financieel Beheerder
                        telefoonnummer:
                          $ref: '#/components/schemas/telefoonnummer'
                        e_mailadres:
                          $ref: '#/components/schemas/e_mailadres'
                  count:
                    $ref: '#/components/schemas/count'
                  next_token:
                    $ref: '#/components/schemas/next_token'
                  filter:
                    description: Parameters used
                    type: object
                    properties:
                      max_rows:
                        $ref: '#/components/schemas/max_rows'
                      next_token:
                        $ref: '#/components/schemas/next_token'
                      company_id:
                        $ref: '#/components/schemas/company_id'
                      hoa_id:
                        $ref: '#/components/schemas/hoa_id'
                      as_of_date:
                        $ref: '#/components/schemas/as_of_date'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
components:
  securitySchemes:
    oauth2_client_credentials:
      type: oauth2
      description: OAuth2 authorization based on Client Credentials
      flows:
        clientCredentials:
          tokenUrl: https://api.twinq.nl/oauth/token
          scopes: {}
  schemas:
    company_id:
      description: TwinQ customer ID
      type: integer
      example: 123
    next_token:
      description: Token for next set of data objects if available
      type: string
      example: >-
        ABC4D65611ECFB58760B12D175139E7A36A07D93EBF657CA3A2DB2A70D1195B013746F0A717F64F3806B3893AA42E20B
    max_rows:
      description: Maximum number of data objects to return per request
      type: integer
      minimum: 1
      maximum: 1000
      default: 500
      example: 500
    gln:
      description: Global Location Number. The GLN always consists of 13 numbers.
      type: integer
      example: 1234567890123
    kvk:
      description: >-
        The Netherlands Chamber of Commerce (Kamer van Koophandel). Always
        consists of 8 numbers, don't forget to include leading zeros.
      type: string
      example: '01234567'
    hoa_code:
      description: HOA code
      type: string
      example: A001
    hoa_id:
      description: HOA ID
      type: integer
      example: 123456
    hoa_naam:
      description: Name of the HOA
      type: string
      example: VvE TwinQ
    count:
      description: Number of returned data objects
      type: integer
      example: 1
    parameter_errors:
      type: array
      items:
        type: object
        properties:
          code:
            type: string
          message:
            type: string
          key:
            type: string
          value:
            type: string
          expected_format:
            type: string
          allowed_values:
            type: string
    validation_error_parameters:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
            parameter_errors:
              $ref: '#/components/schemas/parameter_errors'
    as_of_date:
      description: >-
        Date time in UTC to be used as reference date. Format as in RFC 3339,
        section 5.6
      type: string
      format: date-time
      example: '2025-01-01T12:34:56Z'
    relatie_naam:
      type: string
      example: de Jong, H.
    telefoonnummer:
      type: string
      example: 06 12345678
    telefoonnummers:
      type: array
      items:
        type: object
        properties:
          telefoonnummer:
            $ref: '#/components/schemas/telefoonnummer'
          type_telefoonnummer:
            type: string
            example: Mobiel
    e_mailadressen:
      type: array
      items:
        type: string
        example: voorbeeld@twinq.nl, voorbeeld2@twinq.nl
    adres:
      type: string
      example: teststraat 1, Oosterhout
    postadres:
      type: string
      example: postbus 1, Oosterhout
    e_mailadres:
      type: string
      example: voorbeeld@twinq.nl
  parameters:
    company_id:
      name: company_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/company_id'
    next_token:
      name: next_token
      in: query
      schema:
        $ref: '#/components/schemas/next_token'
    max_rows:
      name: max_rows
      in: query
      schema:
        $ref: '#/components/schemas/max_rows'
    gln:
      name: gln
      in: query
      schema:
        $ref: '#/components/schemas/gln'
    kvk:
      name: kvk
      in: query
      schema:
        $ref: '#/components/schemas/kvk'
    hoa_code:
      name: hoa_code
      in: query
      schema:
        $ref: '#/components/schemas/hoa_code'
    as_of_date:
      name: as_of_date
      in: query
      schema:
        $ref: '#/components/schemas/as_of_date'
    hoa_id:
      name: hoa_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/hoa_id'
  examples:
    company_id:
      value:
        error:
          code: VALIDATION_ERROR
          message: One or more parameter values are invalid
          parameter_errors:
            - message: company_id is not a valid number.
              key: company_id
              value: 123A
  responses:
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/validation_error_parameters'
    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: FORBIDDEN
                  message:
                    type: string
                    example: Unauthorized request.
