> ## Documentation Index
> Fetch the complete documentation index at: https://developer.energy-hub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect URL for a HVAC vendor

> Creates a connect URL to redirect to the IDP of the specified HVAC vendor.



## OpenAPI

````yaml post /v1.0.0/connections/hvacs
openapi: 3.0.1
info:
  description: A service used for connections to vendors
  title: connect-service
  version: 1.0.0
servers:
  - description: Generated server url
    url: https://api.energy-hub.io
security: []
paths:
  /v1.0.0/connections/hvacs:
    post:
      tags:
        - Connection Controller
      summary: Connect URL for a HVAC vendor
      description: >-
        Creates a connect URL to redirect to the IDP of the specified HVAC
        vendor.
      operationId: createConnectUrlForHvacVendor
      parameters:
        - schema:
            type: string
            enum:
              - DARK
              - LIGHT
          in: query
          name: theme
          required: false
        - schema:
            type: string
            enum:
              - ENGLISH
              - GERMAN
              - FRENCH
          in: query
          name: language
          required: false
        - schema:
            type: boolean
          in: query
          name: isUserGdprInformationProvided
          required: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HvacUserLinkRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectUrlResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorMessageDto'
              examples:
                VENDOR_DISABLED:
                  $ref: '#/components/examples/VENDOR_DISABLED'
                BAD_REQUEST:
                  $ref: '#/components/examples/BAD_REQUEST'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
              examples:
                UNAUTHORIZED:
                  $ref: '#/components/examples/UNAUTHORIZED'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
              examples:
                VENDOR_NOT_SUPPORTED:
                  $ref: '#/components/examples/VENDOR_NOT_SUPPORTED'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
              examples:
                SUBSCRIPTION_NOT_FOUND:
                  $ref: '#/components/examples/SUBSCRIPTION_NOT_FOUND'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
              examples:
                REDIRECT_URL_NOT_MATCHING:
                  $ref: '#/components/examples/REDIRECT_URL_NOT_MATCHING'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
              examples:
                VENDOR_ACCOUNT_IS_DISCONNECTED:
                  $ref: '#/components/examples/VENDOR_ACCOUNT_IS_DISCONNECTED'
                VENDOR_COMMUNICATION_ERROR:
                  $ref: '#/components/examples/VENDOR_COMMUNICATION_ERROR'
                VENDOR_AUTHENTICATION_ERROR:
                  $ref: '#/components/examples/VENDOR_AUTHENTICATION_ERROR'
                VENDOR_CONNECTION_ERROR:
                  $ref: '#/components/examples/VENDOR_CONNECTION_ERROR'
      security:
        - API_Key: []
components:
  schemas:
    HvacUserLinkRequest:
      description: An object containing relevant information to link HVAC vendor accounts.
      type: object
      required:
        - redirectUrl
        - userId
        - vendor
      properties:
        redirectUrl:
          minLength: 0
          description: The URL to which the user will be redirected.
          type: string
          maxLength: 2048
          example: >-
            https://www.redirectable-partners-website.com/v1.0.0/endpoint/bea09c5f-9d37-4562-b54a-dedb48d7aaf4
        vendor:
          description: The vendor of the account to be added to the Energy Hub.
          type: string
          enum:
            - VIESSMANN
            - DAIKIN
            - VAILLANT
        userId:
          minLength: 0
          description: The ID of the user for which to create the connect session.
          type: string
          maxLength: 50
          example: 896f9d5a-b618-48a2-98ae-957059bf1bc9
    ConnectUrlResponse:
      description: >-
        An object containing the URL which is used to redirect the user to the
        connect page or vendor login.
      type: object
      required:
        - url
      properties:
        url:
          description: The URL to follow to redirect to connect page or IDP of the vendor.
          type: string
          example: >-
            https://svc-connect.energy-hub.io/bea09c5f-9d37-4562-b54a-dedb48d7aaf4/redirect
    ValidationErrorMessageDto:
      allOf:
        - $ref: '#/components/schemas/ErrorMessageDto'
        - type: object
          properties:
            errorCode:
              description: The error code
              type: string
              example: EXAMPLE_ERROR_CODE
            validationErrors:
              description: List of validation errors
              type: array
              items:
                $ref: '#/components/schemas/ValidationError'
            id:
              format: uuid
              description: The error identifier
              type: string
              example: 7958818d-64d2-4ede-b12b-4786dd2f348b
            message:
              description: The error message
              type: string
              example: Example error message
      type: object
      required:
        - errorCode
        - id
        - message
    ErrorMessageDto:
      type: object
      required:
        - errorCode
        - id
        - message
      properties:
        errorCode:
          description: The error code
          type: string
          example: EXAMPLE_ERROR_CODE
        id:
          format: uuid
          description: The error identifier
          type: string
          example: 7958818d-64d2-4ede-b12b-4786dd2f348b
        message:
          description: The error message
          type: string
          example: Example error message
    ValidationError:
      type: object
      properties:
        field:
          description: Affected field
          type: string
        message:
          description: Validation message
          type: string
  examples:
    VENDOR_DISABLED:
      value:
        errorCode: VENDOR_DISABLED
        id: 5116a930-7dab-4a87-a638-0305f0e8907b
        message: '[CONNECT] Provided vendor has been disabled and is no longer valid.'
    BAD_REQUEST:
      value:
        errorCode: BAD_REQUEST
        validationErrors:
          - field: Affected field
            message: Validation message
        id: 5116a930-7dab-4a87-a638-0305f0e8907b
        message: Bad request
    UNAUTHORIZED:
      value:
        errorCode: UNAUTHORIZED
        id: 5116a930-7dab-4a87-a638-0305f0e8907b
        message: Unauthorized
    VENDOR_NOT_SUPPORTED:
      value:
        errorCode: VENDOR_NOT_SUPPORTED
        id: 5116a930-7dab-4a87-a638-0305f0e8907b
        message: '[CONNECT] Provided vendor is not supported for partner.'
    SUBSCRIPTION_NOT_FOUND:
      value:
        errorCode: SUBSCRIPTION_NOT_FOUND
        id: 5116a930-7dab-4a87-a638-0305f0e8907b
        message: '[SUBSCRIPTION] Requested Subscription not found'
    REDIRECT_URL_NOT_MATCHING:
      value:
        errorCode: REDIRECT_URL_NOT_MATCHING
        id: 5116a930-7dab-4a87-a638-0305f0e8907b
        message: >-
          [CONNECT] Provided redirect url does not match partner management
          redirect url.
    VENDOR_ACCOUNT_IS_DISCONNECTED:
      value:
        errorCode: VENDOR_ACCOUNT_IS_DISCONNECTED
        id: 5116a930-7dab-4a87-a638-0305f0e8907b
        message: '[VENDOR_ACCOUNT] Vendor account is disconnected'
    VENDOR_COMMUNICATION_ERROR:
      value:
        errorCode: VENDOR_COMMUNICATION_ERROR
        id: 5116a930-7dab-4a87-a638-0305f0e8907b
        message: '[VENDOR API] Communication error with Vendor API'
    VENDOR_AUTHENTICATION_ERROR:
      value:
        errorCode: VENDOR_AUTHENTICATION_ERROR
        id: 5116a930-7dab-4a87-a638-0305f0e8907b
        message: '[VENDOR API] Authentication error with Vendor API'
    VENDOR_CONNECTION_ERROR:
      value:
        errorCode: VENDOR_CONNECTION_ERROR
        id: 5116a930-7dab-4a87-a638-0305f0e8907b
        message: '[VENDOR API] Connection cannot be established with Vendor API'
  securitySchemes:
    API_Key:
      in: header
      name: X-API-KEY
      description: API key used for authorization and authentication.
      type: apiKey

````