> ## Documentation Index
> Fetch the complete documentation index at: https://docs.business-os.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Connection

> Erstellt eine Bank-Connect-Session und gibt die Widget-URL zurück. Der User wird zum Widget weitergeleitet, wählt seine Bank und autorisiert den Zugriff via OAuth.

**Cost:** 0 Credits



## OpenAPI

````yaml POST /v2/banking/connect
openapi: 3.1.0
info:
  title: Business OS API
  description: >-
    API für Business OS – Zugang zu DATEV und Banking Enterprise-Schnittstellen.
    Alle Endpoints erfordern einen API Key im `x-api-key` Header. Credits werden
    pro API-Call abgezogen.
  version: 2.0.0
  contact:
    name: Business OS Support
    email: impressum@business-os.de
    url: https://business-os.de/kontakt
servers:
  - url: https://api.business-os.de
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: DATEV Allgemein
    description: >-
      Modulübergreifende DATEV-Endpunkte (z. B. Abo-/Service-Diagnose für
      Mandanten)
  - name: DATEV DUO
    description: DATEV Unternehmen Online — Kassenbuch, Belegbilder und Buchungsvorschläge
  - name: DATEV ReWe - Write
    description: 'DATEV Rechnungswesen — Write: Buchungen, Kontakte, Belegtypen, Steuersätze'
  - name: DATEV ReWe - Read
    description: >-
      DATEV Rechnungswesen — Read (Export): Geschäftsjahre und weitere
      Lesemodule
  - name: Banking AIS
    description: >-
      Account Information Services — Verbindungen, Kontostände und Transaktionen
      verwalten
  - name: Banking PIS
    description: Payment Initiation Services — Zahlungen ausführen und Status abrufen
  - name: Banking Webhooks
    description: Webhook-Konfiguration für Echtzeit-Benachrichtigungen
paths:
  /v2/banking/connect:
    post:
      tags:
        - Banking AIS
      summary: Create Connection
      description: >-
        Erstellt eine Bank-Connect-Session und gibt die Widget-URL zurück. Der
        User wird zum Widget weitergeleitet, wählt seine Bank und autorisiert
        den Zugriff via OAuth.


        **Cost:** 0 Credits
      parameters:
        - $ref: '#/components/parameters/ApiParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: E-Mail-Adresse des Kunden (für Banking-Customer)
                  example: info@mustermann.de
                return_to:
                  type: string
                  format: uri
                  description: Redirect-URL nach erfolgreicher Verbindung
                  example: https://app.business-os.de/close
                scopes:
                  type: array
                  items:
                    type: string
                    enum:
                      - accounts
                      - holder_info
                      - transactions
                  default:
                    - accounts
                    - holder_info
                    - transactions
                  description: >-
                    Banking-Scopes für die Verbindung. Standard deckt alle drei
                    ab: Kontoinfos, Inhaberdaten und Transaktionen.
                  example:
                    - accounts
                    - holder_info
                    - transactions
                custom_fields:
                  type: object
                  description: Benutzerdefinierte Felder (werden im Callback zurückgegeben)
                  example: {}
      responses:
        '200':
          description: Connect Session erstellt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectSessionResponse'
        '401':
          description: Ungültiger API Key
components:
  parameters:
    ApiParam:
      name: api
      in: query
      schema:
        type: string
        enum:
          - partner
          - openbanking
        default: partner
      description: >-
        Banking-API: `partner` (regulierte Banken) oder `openbanking`
        (unregulierte wie AMEX, Revolut)
  schemas:
    ConnectSessionResponse:
      type: object
      description: Antwort beim Erstellen einer Connect-Session
      properties:
        connect_url:
          type: string
          format: uri
          description: URL zum Connect-Widget
          example: https://psd2.business-os.de/connect?token=xxx
        expires_at:
          type: string
          format: date-time
          description: Ablaufzeitpunkt der Session
          example: '2026-03-24T12:44:03Z'
        owner_user_id:
          type: string
          format: uuid
          description: >-
            User-ID, die als Connection-Owner persistiert wird (Dashboard-Flow:
            der authentifizierte Nutzer; API-Key-Flow: der erste Owner-Member
            der Ziel-Org). Identisch mit dem `owner_user_id`-Feld der späteren
            `BankingConnection`-Row.
          example: d90f20ae-f6c1-46da-a080-3d4c86329bf6
        pending_token:
          type: string
          format: uuid
          description: >-
            Opaque Korrelations-Token. Wird in den Banking-`custom_fields`
            mitgegeben und kommt mit jedem Connection-Webhook zurück —
            Server-seitig matched darüber die Pre-Insert-Row mit dem eingehenden
            Banking-Connection-Event (Round-Trip-Key, garantiert dass die neue
            Connection auf der richtigen Org landet).
          example: 8c4a8b18-9b7c-4f9d-9a3e-1a2b3c4d5e6f
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Dein Business OS API Key. Erstelle einen unter
        [app.business-os.de](https://app.business-os.de/) → API Keys.

````