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

# Bank Link API erstellen: Bankverbindung verbinden oder erneuern

> Der Endpoint „Create a Bank Link“ von Didit startet einen Bank-Link-Durchlauf und liefert die gehostete URL, über die die Person ihre Bank verbindet.

Der Endpoint Create a Bank Link von Didit startet auf Ihrem Server einen Durchlauf von Bank Link, um eine Bankverbindung herzustellen oder zu erneuern, und gibt die gehostete `url` zurück.
Jedes Feld hat einen Standardwert, daher besteht die kleinste Anfrage aus `{}` zuzüglich der gewünschten Felder.
Ordnen Sie die zurückgegebene `id` Ihrem Benutzer zu und prüfen Sie das Ergebnis selbst über [Bank Link abrufen](https://docs.didit.me/de/standalone-apis/bank-link-get.md) oder das Webhook-Ereignis `bank.link.completed`.
Siehe [Schnellstart](https://docs.didit.me/de/core-technology/bank-verification/quickstart.md) und [Bank Link](https://docs.didit.me/de/core-technology/bank-verification/bank-link.md).


## OpenAPI

````yaml de/openapi-25.json POST /v3/bank/links/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: Identitätsverifizierungs-API. Authentifizierung mit dem x-api-key-Header.
servers:
  - url: https://verification.didit.me
security: []
tags:
  - name: Bank Data
    description: >-
      Bank Link, Verbindungen, Konten, Guthaben, Transaktionen, Institute und
      Abdeckung. Bankdaten sind für Sandbox-Anwendungen verfügbar. Aufrufe einer
      Live-Anwendung antworten mit `404`, bis der Live-Zugriff angekündigt wird.
      In der Sandbox fallen keine Kosten an. Ein Aufruf mit einem API-Schlüssel
      benötigt einen Schlüssel mit der Berechtigung für Bankdaten (`bank-data`):
      Lesezugriff für Lesevorgänge, Schreibzugriff für Operationen, die etwas
      ändern. Die Kontoprüfung ist die Ausnahme: Sie benötigt Schreibzugriff auf
      Sitzungen oder vollen Zugriff, nicht die Berechtigung für Bankdaten.
      Bankdaten sind nicht Teil des vollen Zugriffs: Ein Schlüssel mit vollem
      Zugriff wird abgelehnt, und der Aufruf antwortet mit `403
      bank_data_access_denied`, bis Sie einen Schlüssel mit dieser Berechtigung
      erstellen. Rohe Bankdaten (Konten, Guthaben, Transaktionen und der
      Änderungs-Feed) lehnen außerdem jede Anfrage ab, die keinen API-Schlüssel
      enthält.


      Jede Ablehnung unter `/v3/bank/` außer der der Kontoprüfung hat denselben
      JSON-Body (`code`, `message`, `request_id`, `field`, `next_action`,
      `retry_after`). Ein Pfad, der keine Operation ist, eine ID, die keine UUID
      ist, oder eine unbekannte Unterressource antwortet für jede Methode mit
      `404 not_found`, und jeder unerwartete Fehler antwortet mit `500
      internal_error` und einer `request_id`. Wo Bankdaten nicht verfügbar sind,
      antwortet jede Operation mit dem standardmäßigen `404` der Plattform,
      genau wie bei einer unbekannten Route.
paths:
  /v3/bank/links/:
    post:
      tags:
        - Bank Data
      summary: Bank-Link erstellen
      description: >-
        Erstellt einen Bank-Link: einen Durchlauf des Ablaufs, in dem eine
        Person eine Bank verbindet oder eine Verbindung erneuert. Senden Sie die
        Person an `url`. Der `client_token` ist für den eingebetteten Bank-Link
        von Didit gedacht, der noch nicht freigegeben ist: Öffnen Sie heute die
        `url`. Ein abgeschlossener Link ergibt eine Verbindung.


        Die kleinste Anfrage ist `{}` plus das, was Sie wünschen. Standardwerte:
        `mode` connect, `access` one_time, `data` nur accounts, `history_days`
        90, `ownership.compare` none, `segment` any, `duplicates` reuse,
        `allow_one_time_fallback` false, und bei laufendem Zugriff eine
        Einwilligung so lange, wie die Bank es erlaubt.


        Die Antwort enthält das Angebot: Der Preis ist an den Link gebunden und
        wird wie angeboten berechnet. Der API-Schlüssel gelangt nie in einen
        Browser oder eine App: Nur die `url` wird an den Browser oder die App
        übermittelt.


        Bestätigen Sie das Ergebnis selbst mit `get_link` oder dem Webhook
        `bank.link.completed`; vertrauen Sie nie einer vom Browser gesendeten
        Link-ID. Verlauf: Senden Sie `history_from` oder `history_days`, nicht
        beides. Sofern die Bank es erlaubt, funktioniert der laufende Zugriff
        bis zum Ende der Einwilligung weiter; das tatsächliche Datum steht bei
        jeder Verbindung.


        Benötigt einen API-Schlüssel mit der Berechtigung für Bankdaten
        (`bank-data`): Schreibzugriff für diesen Vorgang, der etwas ändert. Ein
        Schlüssel mit vollem Zugriff schließt sie nicht ein: Gewähren Sie sie
        beim Erstellen des Schlüssels ausdrücklich, sonst antwortet der Aufruf
        mit `403 bank_data_access_denied`.
      operationId: createBankLink
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankLinkCreateRequest'
            example:
              mode: connect
              access: ongoing
              country: ESP
              segment: business
              data:
                - accounts
                - balances
                - transactions
              history_from: '2026-01-01'
              consent_days: 180
              ownership:
                compare: none
              end_user:
                reference: client-7731
                email: ana@example.com
              redirect_url: https://app.example.com/bank/return
              allowed_origins:
                - https://app.example.com
              language: es
              vendor_data: client-7731
      responses:
        '201':
          description: Der Link wurde erstellt.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankLink'
              examples:
                Ongoing business connection:
                  summary: Laufender Zugriff auf ein Geschäftskonto in Spanien
                  value:
                    id: 0b9c4f1e-6a2d-4e8b-9f31-7c5d2e1a8b40
                    mode: connect
                    access: ongoing
                    status: created
                    url: https://verify.didit.me/bank/link/example-link-token
                    client_token: example-client-token
                    expires_at: '2026-11-21T13:00:00Z'
                    connection_id: null
                    check_id: null
                    reused: false
                    error: null
                    quote:
                      id: 7a3e9c52-1d84-4b06-8f2a-c5e0b9d17a43
                      lines:
                        - meter: bank_data_connection_month
                          unit: connection_month
                          price_usd: '0.9000'
                      fallback_lines: null
                      total_usd: '0.9000'
                      valid_until: '2026-11-21T13:00:00Z'
                      scopes:
                        - accounts
                        - balances
                        - transactions
                    vendor_data: client-7731
        '400':
          description: >-
            Die Anfrage wurde vor jeglicher Prüfung abgelehnt. `field` nennt,
            was korrigiert werden muss: `invalid_request` für einen Wert
            außerhalb seines Bereichs oder eine nicht zulässige Kombination,
            sowie die spezifischeren hier angegebenen Codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Bank cannot keep access open:
                  summary: Die Bank kann den Zugriff nicht aufrechterhalten
                  value:
                    code: ongoing_access_not_available
                    message: >-
                      This bank cannot keep access open. Use access one_time or
                      choose another bank.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: institution_id
                    next_action: create_link
                    retry_after: null
                History window ambiguous:
                  summary: Verlaufszeitraum mehrdeutig
                  value:
                    code: history_window_ambiguous
                    message: Send history_from or history_days, not both.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: history_from
                    next_action: null
                    retry_after: null
                Redirect URL not registered:
                  summary: Weiterleitungs-URL nicht registriert
                  value:
                    code: redirect_url_not_registered
                    message: >-
                      This redirect_url is not one of the return addresses
                      registered for your application. Addresses are matched
                      exactly (scheme, host, port, path and query); in sandbox a
                      plain http localhost address needs no registration. Send a
                      registered address, or leave redirect_url out (automatic
                      return to your page is then not promised).
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: redirect_url
                    next_action: null
                    retry_after: null
                Segment not available:
                  summary: Segment nicht verfügbar
                  value:
                    code: segment_not_available
                    message: >-
                      This bank does not offer this kind of account through Bank
                      Link.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: segment
                    next_action: null
                    retry_after: null
                Window not available:
                  summary: Zeitfenster nicht verfügbar
                  value:
                    code: window_not_available
                    message: This bank cannot deliver the requested history window.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: history_from
                    next_action: null
                    retry_after: null
                Invalid request:
                  summary: Ungültige Anfrage
                  value:
                    code: invalid_request
                    message: The request is not valid.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: expires_in
                    next_action: null
                    retry_after: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: >-
            Das Guthaben reicht nicht für den angebotenen Preis aus. Laden Sie
            das Guthaben auf und versuchen Sie es erneut.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Insufficient credits:
                  summary: Unzureichendes Guthaben
                  value:
                    code: insufficient_credits
                    message: The balance cannot cover the quoted price.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: top_up_balance
                    retry_after: null
        '403':
          description: >-
            Abgelehnt: Ihr Vertrag enthält keinen Tarif für dieses Land, oder
            dem Schlüssel fehlt die Berechtigung für Bankdaten.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                No contract rate:
                  summary: Kein Vertragstarif
                  value:
                    code: contract_rate_missing
                    message: Your contract has no rate for bank data in this country.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: null
                    retry_after: null
                Bank data not allowed:
                  summary: Bankdaten nicht zulässig
                  value:
                    code: bank_data_access_denied
                    message: >-
                      Bank data calls need an API key that carries the Bank data
                      permission.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: enable_bank_data_access
                    retry_after: null
        '404':
          description: Die Ressource existiert in dieser Anwendung und Umgebung nicht.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Not found:
                  summary: Nicht gefunden
                  value:
                    code: not_found
                    message: The resource does not exist.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: null
                    retry_after: null
        '429':
          $ref: '#/components/responses/RateLimitedWrite'
        '500':
          $ref: '#/components/responses/BankDataInternalError'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST 'https://verification.didit.me/v3/bank/links/' \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "mode": "connect",
                "access": "ongoing",
                "country": "ESP",
                "segment": "business",
                "data": [
                  "accounts",
                  "balances",
                  "transactions"
                ],
                "history_from": "2026-01-01",
                "consent_days": 180,
                "ownership": {
                  "compare": "none"
                },
                "end_user": {
                  "reference": "client-7731",
                  "email": "ana@example.com"
                },
                "redirect_url": "https://app.example.com/bank/return",
                "allowed_origins": [
                  "https://app.example.com"
                ],
                "language": "es",
                "vendor_data": "client-7731"
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.bank.create_link(
                mode="connect",
                access="ongoing",
                country="ESP",
                segment="business",
                data=["accounts", "balances", "transactions"],
                history_from="2026-01-01",
                consent_days=180,
                ownership={
                    "compare": "none",
                },
                end_user={
                    "reference": "client-7731",
                    "email": "ana@example.com",
                },
                redirect_url="https://app.example.com/bank/return",
                allowed_origins=["https://app.example.com"],
                language="es",
                vendor_data="client-7731",
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: |-
            import Didit from "@didit-protocol/sdk-node";

            // Reads DIDIT_API_KEY.
            const didit = new Didit();

            const result = await didit.bank.createLink({
              mode: "connect",
              access: "ongoing",
              country: "ESP",
              segment: "business",
              data: ["accounts", "balances", "transactions"],
              history_from: "2026-01-01",
              consent_days: 180,
              ownership: {
                compare: "none",
              },
              end_user: {
                reference: "client-7731",
                email: "ana@example.com",
              },
              redirect_url: "https://app.example.com/bank/return",
              allowed_origins: ["https://app.example.com"],
              language: "es",
              vendor_data: "client-7731",
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Bank.CreateLink(ctx, didit.BankCreateLinkParams{\n\tBody: didit.BankLinkCreateRequest{\n\t\tMode:        didit.Some(didit.BankLinkCreateRequestMode(\"connect\")),\n\t\tAccess:      didit.Some(didit.BankLinkCreateRequestAccess(\"ongoing\")),\n\t\tCountry:     didit.String(\"ESP\"),\n\t\tSegment:     didit.Some(didit.BankLinkCreateRequestSegment(\"business\")),\n\t\tData:        didit.Some([]didit.BankLinkCreateRequestData{\"accounts\", \"balances\", \"transactions\"}),\n\t\tHistoryFrom: didit.String(\"2026-01-01\"),\n\t\tConsentDays: didit.Int(180),\n\t\tOwnership: didit.Some(didit.BankLinkOwnershipRequest{\n\t\t\tCompare: didit.Some(didit.BankLinkOwnershipRequestCompare(\"none\")),\n\t\t}),\n\t\tEndUser: didit.Some(didit.BankLinkEndUser{\n\t\t\tReference: didit.String(\"client-7731\"),\n\t\t\tEmail:     didit.String(\"ana@example.com\"),\n\t\t}),\n\t\tRedirectURL:    didit.String(\"https://app.example.com/bank/return\"),\n\t\tAllowedOrigins: didit.Some([]string{\"https://app.example.com\"}),\n\t\tLanguage:       didit.String(\"es\"),\n\t\tVendorData:     didit.String(\"client-7731\"),\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: >-
            import java.time.LocalDate;

            import java.util.List;

            import me.didit.Didit;

            import me.didit.types.BankLinkCreateRequest;

            import me.didit.types.BankLinkEndUser;

            import me.didit.types.BankLinkOwnershipRequest;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.bank().createLink(BankLinkCreateRequest.builder()
                    .mode(BankLinkCreateRequest.Mode.of("connect"))
                    .access(BankLinkCreateRequest.Access.of("ongoing"))
                    .country("ESP")
                    .segment(BankLinkCreateRequest.Segment.of("business"))
                    .data(List.of(BankLinkCreateRequest.Data.of("accounts"), BankLinkCreateRequest.Data.of("balances"), BankLinkCreateRequest.Data.of("transactions")))
                    .historyFrom(LocalDate.parse("2026-01-01"))
                    .consentDays(180L)
                    .ownership(BankLinkOwnershipRequest.builder()
                            .compare(BankLinkOwnershipRequest.Compare.of("none"))
                            .build())
                    .endUser(BankLinkEndUser.builder()
                            .reference("client-7731")
                            .email("ana@example.com")
                            .build())
                    .redirectUrl("https://app.example.com/bank/return")
                    .allowedOrigins(List.of("https://app.example.com"))
                    .language("es")
                    .vendorData("client-7731")
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // Reads DIDIT_API_KEY.
            $didit = new DiditClient();

            $result = $didit->bank->createLink([
                'mode' => 'connect',
                'access' => 'ongoing',
                'country' => 'ESP',
                'segment' => 'business',
                'data' => ['accounts', 'balances', 'transactions'],
                'history_from' => '2026-01-01',
                'consent_days' => 180,
                'ownership' => [
                    'compare' => 'none',
                ],
                'end_user' => [
                    'reference' => 'client-7731',
                    'email' => 'ana@example.com',
                ],
                'redirect_url' => 'https://app.example.com/bank/return',
                'allowed_origins' => ['https://app.example.com'],
                'language' => 'es',
                'vendor_data' => 'client-7731',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.bank.create_link(
              mode: "connect",
              access: "ongoing",
              country: "ESP",
              segment: "business",
              data: ["accounts", "balances", "transactions"],
              history_from: "2026-01-01",
              consent_days: 180,
              ownership: {
                compare: "none",
              },
              end_user: {
                reference: "client-7731",
                email: "ana@example.com",
              },
              redirect_url: "https://app.example.com/bank/return",
              allowed_origins: ["https://app.example.com"],
              language: "es",
              vendor_data: "client-7731"
            )
            puts result.to_h
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            var result = await client.Bank.CreateLinkAsync(new
            BankLinkCreateRequest

            {
                Mode = new BankLinkCreateRequestMode("connect"),
                Access = new BankLinkCreateRequestAccess("ongoing"),
                Country = "ESP",
                Segment = new BankLinkCreateRequestSegment("business"),
                Data = new BankLinkCreateRequestData[] { "accounts", "balances", "transactions" },
                HistoryFrom = "2026-01-01",
                ConsentDays = 180,
                Ownership = new BankLinkOwnershipRequest
                {
                    Compare = new BankLinkOwnershipRequestCompare("none"),
                },
                EndUser = new BankLinkEndUser
                {
                    Reference = "client-7731",
                    Email = "ana@example.com",
                },
                RedirectUrl = "https://app.example.com/bank/return",
                AllowedOrigins = new string[] { "https://app.example.com" },
                Language = "es",
                VendorData = "client-7731",
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Optionaler Schlüssel zur Wiederholungssicherheit für einen Vorgang, den
        Sie selbst wählen, bis zu 255 Zeichen (eine UUID eignet sich). Eine
        Anfrage, die mit demselben Schlüssel, demselben Endpoint, denselben
        Query-Parametern und demselben Body wiederholt wird, erhält die erste
        Antwort mit demselben Status und demselben Body zurück und wird kein
        zweites Mal ausgeführt oder berechnet. Derselbe Schlüssel mit einem
        anderen Endpoint, anderen Query-Parametern oder einem anderen Body
        liefert `409` mit `idempotency_key_reused`. Solange die erste Anfrage
        noch läuft, liefert er `409` mit `idempotency_key_in_progress` und
        `Retry-After`. Eine fehlgeschlagene Anfrage (jeder `4xx`- oder
        `5xx`-Fehler) wird nicht gespeichert, sodass Sie sie mit demselben
        Schlüssel erneut senden können. Schlüssel gehören zu Ihrer Anwendung,
        unabhängig davon, ob Sie mit einem API-Schlüssel oder einem
        Zugriffstoken aufrufen. Siehe [Wiederholungsversuche und
        Idempotenz](/de/integration/api-errors#wiederholungsversuche-und-idempotenz).
      schema:
        type: string
        minLength: 1
        maxLength: 255
  schemas:
    BankLinkCreateRequest:
      type: object
      description: >-
        Erstellen Sie einen Bank-Link. Die kleinste Anfrage ist `{}` plus das,
        was Sie wünschen: Jedes Feld hat einen Standardwert.
      properties:
        mode:
          type: string
          enum:
            - connect
            - renew
          description: >-
            `connect` (Standard) erstellt eine neue Verbindung. `renew` benötigt
            `connection_id` und übernimmt die Einstellungen dieser Verbindung.
          default: connect
        connection_id:
          type: string
          description: 'Die zu erneuernde Verbindung. Nur mit `mode: renew`.'
          format: uuid
        access:
          type: string
          enum:
            - one_time
            - ongoing
          description: >-
            `one_time` (Standard) liest die Daten einmal aus. `ongoing` hält den
            Zugriff offen, bis die Einwilligung endet oder jemand ihn beendet.
            Mit gesetztem `institution_id` antwortet eine Bank, die keinen
            dauerhaften Zugriff offen halten kann, mit `400
            ongoing_access_not_available`, bevor ein Bildschirm angezeigt wird.
            Ohne sie listet die Bankauswahl nur Banken auf, die dies können.
          default: one_time
        country:
          type: string
          description: >-
            Optional. Ohne diese Angabe wählt die Person unter den Ländern aus,
            die Ihre Anwendung aktiviert hat. Es muss ein Land sein, das Bank
            Link unterstützt; jedes andere, auch `ZZZ`, antwortet mit `400
            invalid_request` und `field: country`. Ein leerer Request-Body
            bleibt gültig.
          pattern: ^[A-Z]{3}$
        institution_id:
          type: string
          description: >-
            Optionale Bank zur Vorauswahl, aus `list_institutions`. Überspringt
            die Auswahl.
          maxLength: 64
        segment:
          type: string
          enum:
            - personal
            - business
            - any
          description: >-
            Filtert die Bankauswahl und gibt an, welchen Login die Bank öffnet,
            wenn sie Logins trennt. Standardwert `any`.
          default: any
        data:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
          description: >-
            Was gelesen werden soll. `accounts` ist immer enthalten: Name, Typ,
            Währung, Kennungen und der Name des Kontoinhabers, sofern die Bank
            ihn teilt. Standard ist `["accounts"]`.
          default:
            - accounts
          maxItems: 3
        history_days:
          type: integer
          description: >-
            Anzahl der Tage an Transaktionshistorie, die angefordert werden, 1
            bis 365, Standard 90. Die Bank kann weniger liefern: Jedes Konto
            meldet in `history_coverage`, was geliefert wurde. Kann nicht
            zusammen mit `history_from` gesendet werden.
          minimum: 1
          maximum: 365
          default: 90
        history_from:
          type: string
          description: >-
            Startdatum des abzurufenden Verlaufs anstelle von `history_days`.
            Kann nicht zusammen mit `history_days` gesendet werden: Beides
            zusammen führt zu `400 history_window_ambiguous`. Für ein Datum, das
            älter als 365 Tage ist oder in der Zukunft liegt, wird `400
            window_not_available` zurückgegeben.
          format: date
        extended_history:
          type: string
          enum:
            - standard
            - allow_extra_auth
          description: >-
            `allow_extra_auth` ermöglicht es einer Bank, die eine weitere
            Bestätigung verlangt, ältere Historie freizugeben.
          default: standard
        consent_days:
          type: integer
          description: >-
            Nur bei Ongoing. Anzahl der Tage, für die Sie die Bank bitten, den
            Zugriff offen zu halten, 1 oder mehr. Standard: der längste
            Zeitraum, den die Bank erlaubt. Die Verbindung meldet das Datum, das
            die Bank tatsächlich gewährt hat, in `consent.expires_at`. Bei
            `access: one_time` antwortet sie mit `400 invalid_request` und
            `field: consent_days`.
          minimum: 1
          maximum: 32767
        ownership:
          $ref: '#/components/schemas/BankLinkOwnershipRequest'
        end_user:
          $ref: '#/components/schemas/BankLinkEndUser'
        redirect_url:
          type: string
          description: >-
            Wohin der Browser am Ende geht, mit `link_id`, `status` und einem
            signierten `state` (nur zur Anzeige: der Webhook und `get_link` sind
            maßgeblich). In einer Sandbox-Anwendung benötigt eine einfache
            `http`-Adresse von `localhost`, `127.0.0.1` oder `[::1]` (beliebiger
            Port und Pfad, ohne Zugangsdaten, ohne Fragment) keine
            Registrierung. Jede andere Adresse antwortet mit `400
            redirect_url_not_registered`: Die Registrierung anderer Adressen ist
            noch nicht verfügbar. Ohne `redirect_url` landet die Person auf der
            eigenen Ergebnisseite von Didit.
          format: uri
          maxLength: 2048
        allowed_origins:
          type: array
          items:
            type: string
            format: uri
          description: >-
            Akzeptiert, aber derzeit nicht verwendet: reserviert für Didits
            eingebetteten Bank Link, der noch nicht veröffentlicht ist.
            HTTPS-Ursprünge, bis zu 50.
          maxItems: 50
        language:
          type: string
          description: >-
            Optionaler Sprachcode wie `es` oder `pt-BR`. Andernfalls die
            Browsersprache.
          pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})?$
          maxLength: 16
        vendor_data:
          type: string
          description: >-
            Ihre eigene Referenz, die im Link und in der Verbindung
            zurückgegeben wird.
          maxLength: 255
        expires_in:
          type: integer
          description: >-
            Gültigkeitsdauer des Links in Sekunden, 300 bis 86400. Standard
            3600.
          minimum: 300
          maximum: 86400
          default: 3600
        duplicates:
          type: string
          enum:
            - reuse
            - allow
          description: >-
            `reuse` (Standardwert) schließt einen Link ab, der auf bereits
            gemeinsam genutzte Konten verweist, als Erneuerung dieser
            Verbindung. `allow` erstellt eine unabhängige zweite Verbindung.
          default: reuse
        allow_one_time_fallback:
          type: boolean
          description: >-
            Bei `ongoing` kann die Person mit einem einmaligen Auslesen
            fortfahren, wenn eine Bank keinen dauerhaften Zugriff offen halten
            kann, nachdem die Person den eingeschränkten Zugriff auf dem
            Bildschirm der Bank bestätigt hat. Das Angebot zeigt, was dies
            kostet. Nur bei `access: ongoing`: Bei einmaligem Zugriff wird mit
            `400 invalid_request` und `field: allow_one_time_fallback`
            geantwortet.
          default: false
        accept_reduced_grant:
          type: boolean
          description: >-
            Wenn die Bank oder die Person weniger gewährt, als Sie angefragt
            haben, schließen Sie den Link ab und berechnen nur die gewährten
            Scopes. Andernfalls endet der Link mit `failed` und `reduced_grant`,
            und nichts wird berechnet.
          default: false
        sandbox:
          type: object
          description: >-
            Nur für Sandbox-Anwendungen: wählt den Didit-Test-Bank-Kunden aus.
            In einer Live-Anwendung wird er ignoriert.
          properties:
            persona:
              type: string
              enum:
                - personal_basic
                - business_multi
                - long_history
                - pending
                - sparse_fields
                - no_ongoing
              description: >-
                Der Test-Bank-Kunde: `personal_basic` (ein aktuelles Konto, 60
                Bewegungen), `business_multi` (drei Konten eines Unternehmens),
                `long_history` (ein Konto mit 400 Tagen und 1.400 Bewegungen;
                ein Abruf liefert die letzten 365 Tage, setzen Sie daher
                `history_days` auf 365), `pending` (enthält ausstehende
                Transaktionen), `sparse_fields` (kein Wertstellungsdatum, keine
                Gegenkonto-IBAN, keine Bankreferenz) oder `no_ongoing` (eine
                Bank, die nur einmaligen Zugriff erlaubt: verwenden Sie
                `allow_one_time_fallback`).
            switches:
              type: array
              items:
                type: string
                enum:
                  - partial_grant
                  - renewal_other_login
                  - expired_cursor
                  - webhook_twice
                  - midnight_booking
                  - blocked_popup
                  - bank_app_return
              description: >-
                Wird akzeptiert und für den Sandbox-Simulator reserviert: Die
                Werte ändern derzeit nichts.
    BankLink:
      type: object
      description: >-
        Ein Durchlauf von Bank Link für eine Person: eine Bank anbinden oder
        eine Verbindung erneuern. Bestätigen Sie einen Link selbst mit
        `get_link`: vertrauen Sie nie einer vom Browser gesendeten ID.
      properties:
        id:
          type: string
          description: Kennung des Links.
          format: uuid
        mode:
          type: string
          enum:
            - connect
            - renew
        access:
          type: string
          enum:
            - one_time
            - ongoing
        status:
          type: string
          enum:
            - created
            - opened
            - connecting
            - completed
            - cancelled
            - expired
            - failed
          description: >-
            Status des Links. `completed`, `cancelled`, `expired` und `failed`
            sind endgültig.
        url:
          type: string
          description: >-
            Die gehostete Verifizierungsseite, zu der die Person geleitet werden
            soll. Wird nur beim Erstellen des Verifizierungslinks zurückgegeben;
            bei späteren Abfragen `null`, weil das Token nicht gespeichert wird.
          nullable: true
          format: uri
        client_token:
          type: string
          description: >-
            Das Token für den eingebetteten Bank Link von Didit, der noch nicht
            freigegeben ist: Öffnen Sie heute `url`. Wird nur bei der Erstellung
            des Links zurückgegeben; bei späteren Abfragen `null`. Es hat einen
            einzigen Zweck und ist nur kurz gültig. Es enthält keine
            personenbezogenen Daten. Protokollieren Sie es niemals.
          nullable: true
        expires_at:
          type: string
          description: Wann ein nicht eingelöster Link nicht mehr funktioniert.
          format: date-time
        connection_id:
          type: string
          description: >-
            Die Verbindung, die dieser Link erstellt oder erneuert hat, sobald
            `status` `completed` ist.
          format: uuid
          nullable: true
        check_id:
          type: string
          description: >-
            Das Ergebnis zur Eigentümerstruktur dieses Links, wenn er
            `ownership.compare` mit einem anderen Wert als `none` angefordert
            hat.
          format: uuid
          nullable: true
        reused:
          type: boolean
          description: >-
            `true`, wenn der Link als Erneuerung einer bestehenden Verbindung
            abgeschlossen wurde, weil die Person genau diese Konten bereits
            gemeinsam nutzt (`duplicates: reuse`). Es wird nichts doppelt
            berechnet.
        error:
          allOf:
            - $ref: '#/components/schemas/BankLinkError'
          nullable: true
          description: >-
            Warum der Link fehlgeschlagen ist, wenn `status` `failed` ist.
            Andernfalls `null`.
        quote:
          $ref: '#/components/schemas/BankLinkQuote'
        vendor_data:
          type: string
          description: Ihre Referenz aus der Anfrage.
          nullable: true
      required:
        - id
        - mode
        - access
        - status
        - url
        - client_token
        - expires_at
        - connection_id
        - check_id
        - reused
        - error
        - quote
        - vendor_data
    BankDataError:
      type: object
      description: Fehler-Body jeder Bankdaten-Operation. Jedes Feld ist immer vorhanden.
      properties:
        code:
          type: string
          enum:
            - ongoing_access_not_available
            - segment_not_available
            - window_not_available
            - history_window_ambiguous
            - redirect_url_not_registered
            - link_origin_not_allowed
            - bank_data_access_denied
            - connection_not_active
            - consent_expired
            - renewal_not_needed
            - renewal_window_expired
            - access_removed
            - refresh_limit_reached
            - cursor_expired
            - page_expired
            - invalid_cursor
            - page_token_mismatch
            - contract_rate_missing
            - insufficient_credits
            - invalid_request
            - not_found
            - internal_error
          description: >-
            Maschinenlesbarer Fehlercode. Richten Sie Ihre Logik danach aus, nie
            nach `message`.
        message:
          type: string
          description: >-
            Verständliche Erklärung für Entwickler. Der Wortlaut kann sich
            ändern; parsen Sie ihn nicht.
        request_id:
          type: string
          description: >-
            Kennung dieser Anfrage. Geben Sie sie an, wenn Sie den Support
            kontaktieren.
        field:
          type: string
          description: >-
            Das Anfragefeld, das korrigiert werden muss, wenn sich der Fehler
            auf ein einzelnes Feld bezieht. Andernfalls `null`.
          nullable: true
        next_action:
          type: string
          enum:
            - retry_later
            - renew_connection
            - create_link
            - restart_from_cursor
            - restart_read
            - top_up_balance
            - enable_bank_data_access
            - contact_support
            - null
          description: >-
            Was als Nächstes zu tun ist, damit ein Client handeln kann, ohne zu
            raten. `null`, wenn es keinen Standardschritt gibt.
          nullable: true
        retry_after:
          type: integer
          description: >-
            Sekunden, die vor einem Wiederholungsversuch zu warten sind. Wird
            bei Rate-Limit-Fehlern und vorübergehenden Fehlern gesetzt,
            andernfalls `null`.
          nullable: true
      required:
        - code
        - message
        - request_id
        - field
        - next_action
        - retry_after
      example:
        code: ongoing_access_not_available
        message: >-
          This bank cannot keep access open. Use access one_time or choose
          another bank.
        request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
        field: institution_id
        next_action: create_link
        retry_after: null
    BankLinkOwnershipRequest:
      type: object
      description: >-
        Optionaler Vergleich des Kontoinhabers mit einer Person oder einem
        Unternehmen.
      properties:
        compare:
          type: string
          enum:
            - none
            - person
            - business
          description: >-
            Womit der Kontoinhaber abgeglichen wird. `none` (Standard) liefert
            kein Ergebnis und benötigt keine Referenz. `person` benötigt
            `reference_identity` oder `session_id`. `business` benötigt
            `business` oder `business_session_id`. Senden Sie genau eine
            Referenz der Art, mit der Sie abgleichen, und bei `none` keine.
          default: none
        match:
          type: string
          enum:
            - any_holder
            - all_holders
          description: >-
            Ob ein rechtlicher Kontoinhaber oder alle rechtlichen Kontoinhaber
            übereinstimmen müssen. Vertreter zählen nie.
          default: any_holder
        reference_identity:
          type: object
          description: >-
            Vom Aufrufer übermittelte Werte, die mit dem Kontoinhaber
            abgeglichen werden. Dürfen nicht zusammen mit `session_id` gesendet
            werden.
          properties:
            full_name:
              type: string
              maxLength: 255
            date_of_birth:
              type: string
              format: date
            address:
              type: string
              maxLength: 500
            phone:
              type: string
              maxLength: 64
            email:
              type: string
              maxLength: 255
        session_id:
          type: string
          description: >-
            Eine abgeschlossene Didit-Verifizierungssitzung der Person als
            Vergleich. Kann nicht zusammen mit `reference_identity` gesendet
            werden.
          format: uuid
        business:
          type: object
          description: Das Unternehmen, mit dem der Kontoinhaber verglichen werden soll.
          properties:
            legal_name:
              type: string
              maxLength: 255
            registration_id:
              type: string
              maxLength: 128
          required:
            - legal_name
        business_session_id:
          type: string
          description: >-
            Eine Didit-Unternehmensverifizierung, mit der ein Vergleich
            durchgeführt werden soll. Kann nicht zusammen mit `business`
            gesendet werden.
          format: uuid
    BankLinkEndUser:
      type: object
      description: Die Person oder das Unternehmen, die bzw. das das Konto verbindet.
      properties:
        reference:
          type: string
          description: >-
            Ihre eigene ID für die Person oder das Unternehmen. Durchsuchbar mit
            `end_user_reference` und dient dazu, eine wiederholte Verbindung zu
            erkennen.
          maxLength: 255
        email:
          type: string
          description: >-
            Optional. Wenn der Bankweg für die Person eine verifizierte Adresse
            benötigt und Sie keine gesendet haben, fragt Bank Link die Person
            danach. Wird niemals für Marketing verwendet.
          format: email
          maxLength: 254
    BankLinkError:
      type: object
      description: >-
        Der Grund, aus dem ein Link mit `failed` beendet wurde. Es wurde nichts
        veröffentlicht oder berechnet.
      properties:
        code:
          type: string
          enum:
            - duplicate_conflict
            - renewal_login_mismatch
            - reduced_grant
            - corporate_approval_not_supported
            - ongoing_access_not_available
            - bank_unavailable
            - bank_cancelled
            - consent_declined
            - read_limit
            - renewal_not_needed
            - renewal_window_expired
            - first_sync_failed
          description: >-
            Warum der Link fehlgeschlagen ist. Ein fehlgeschlagener Link ist
            kein HTTP-Fehler: Der Link wird mit `status: failed` und diesem
            Objekt zurückgegeben. Ein Erneuerungslink, dessen Verbindung sich
            inzwischen geändert hat, liefert `renewal_not_needed` oder
            `renewal_window_expired`.
        message:
          type: string
          description: Verständliche Erklärung für Entwickler.
        conflicts_with:
          type: array
          nullable: true
          items:
            type: string
            format: uuid
          description: >-
            Bei `duplicate_conflict`: die IDs der aktiven Verbindungen, die sich
            überschneiden. Erneuern Sie eine davon oder erstellen Sie den Link
            erneut mit `duplicates: allow`.
      required:
        - code
        - message
        - conflicts_with
    BankLinkQuote:
      type: object
      description: >-
        Der Preis eines Links, der bei seiner Erstellung festgeschrieben wird.
        Berechnet wird der Preis aus dem Angebot. Lesevorgänge werden nie
        abgerechnet.
      properties:
        id:
          type: string
          description: Kennung des Angebots.
          format: uuid
        lines:
          type: array
          items:
            $ref: '#/components/schemas/BankLinkQuoteLine'
          description: >-
            Die Positionen, die dieser Link für die angeforderten Bereiche
            berechnet.
        fallback_lines:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/BankLinkQuoteLine'
          description: >-
            Was ein einmaliger Fallback berechnen würde, nur wenn der Link mit
            `allow_one_time_fallback` erstellt wurde. Er wird in der Antwort zur
            Erstellung angezeigt und ist andernfalls `null`. Ein einmaliger
            Abruf mit Daten kann mehr kosten als ein erster Monat laufender
            Zugriff.
        total_usd:
          type: string
          description: >-
            Summe der `lines` in USD. Die Summe kann nur sinken: bei einer
            reduzierten Freigabe oder wenn die Person ein Land mit einem
            niedrigeren Preis wählt.
          pattern: ^-?\d+(\.\d+)?$
        valid_until:
          type: string
          description: >-
            Das Angebot ist an den Link gebunden und gilt für dessen gesamte
            Laufzeit, daher entspricht es `expires_at`.
          format: date-time
        scopes:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
          description: Die Datenbereiche bestimmen die Preise des Angebots.
      required:
        - id
        - lines
        - fallback_lines
        - total_usd
        - valid_until
        - scopes
    RateLimitBudgetError:
      type: object
      description: >-
        Wird nur bei einer Ablehnung durch das Rate-Limit-Budget der Middleware
        zurückgegeben. Andere 429-Fehler, einschließlich Idempotenzkonflikten
        und endpunktspezifischer Obergrenzen, garantieren diese Metadatenfelder
        nicht.
      required:
        - detail
        - reference
        - limit
        - remaining
        - reset
        - window_seconds
      properties:
        detail:
          type: string
          description: Bestehende, für Menschen lesbare Meldung zur Budgetablehnung.
        reference:
          type: string
          pattern: ^RL-[0-9a-f]{32}$
          description: >-
            Opake Support-Referenz: RL- gefolgt von 32 hexadezimalen Zeichen der
            UUID in Kleinbuchstaben.
        limit:
          type: integer
          description: >-
            Budget für den überschrittenen Bereich; entspricht
            X-RateLimit-Limit.
        remaining:
          type: integer
          minimum: 0
          description: >-
            Verbleibendes Budget, auf null begrenzt. Entspricht
            X-RateLimit-Remaining.
        reset:
          type: integer
          format: int64
          description: >-
            Reset-Zeit des Zeitfensters in Unix-Sekunden; entspricht
            X-RateLimit-Reset.
        window_seconds:
          type: integer
          description: >-
            Dauer des festen Zeitfensters in Sekunden, nicht die verbleibende
            Wartezeit. Vor einem erneuten Versuch Retry-After beachten.
      example:
        detail: >-
          Write request rate limit exceeded. You can make up to 300 requests per
          minute.
        reference: RL-00000000000040008000000000000001
        limit: 300
        remaining: 0
        reset: 1794358860
        window_seconds: 60
    BankLinkQuoteLine:
      type: object
      description: Eine bepreiste Position eines Angebots.
      properties:
        meter:
          type: string
          description: >-
            Was berechnet wird, zum Beispiel `bank_data_connection_month` oder
            `bank_verification`.
          example: bank_data_connection_month
        unit:
          type: string
          description: >-
            Was eine Einheit ist, zum Beispiel `connection_month` oder
            `completed_sign_in`.
          example: connection_month
        price_usd:
          type: string
          description: >-
            Preis pro Einheit in USD, ein Dezimalstring mit 4 Nachkommastellen.
            Beträge in Beispielen dienen nur der Veranschaulichung; den Preis
            für ein Land finden Sie auf der Preisseite.
          pattern: ^-?\d+(\.\d+)?$
          example: '0.9000'
      required:
        - meter
        - unit
        - price_usd
  responses:
    Unauthorized:
      description: Nicht autorisiert
      content:
        application/json:
          examples:
            Invalid API Key:
              summary: Ungültiger API-Schlüssel
              value:
                detail: Invalid API Key.
    RateLimitedWrite:
      description: >-
        Das gemeinsame Schreiblimit von 300 Anfragen pro Minute und
        API-Schlüssel wurde überschritten. Beachten Sie `Retry-After`, bevor Sie
        es erneut versuchen.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitBudgetError'
          example:
            detail: >-
              Write request rate limit exceeded. You can make up to 300 requests
              per minute.
            reference: RL-00000000000040008000000000000001
            limit: 300
            remaining: 0
            reset: 1794358860
            window_seconds: 60
      headers:
        Retry-After:
          $ref: '#/components/headers/BudgetRetryAfter'
        X-RateLimit-Scope:
          $ref: '#/components/headers/BudgetXRateLimitScope'
        X-RateLimit-Limit:
          $ref: '#/components/headers/BudgetXRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/BudgetXRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/BudgetXRateLimitReset'
    BankDataInternalError:
      description: >-
        Bei Didit ist etwas schiefgelaufen. Jeder unerwartete Fehler unter
        `/v3/bank/` antwortet im Bank-Fehlerformat, niemals mit einer
        HTML-Seite: Geben Sie dem Support die `request_id` an.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Internal error:
              summary: Ein unerwarteter Fehler
              value:
                code: internal_error
                message: >-
                  Something went wrong on our side. Quote the request_id to
                  support.
                request_id: 3f6a1c8e92b54d07a1e38c4b7f0d2e59
                field: null
                next_action: contact_support
                retry_after: null
  headers:
    BudgetRetryAfter:
      description: >-
        Wartezeit in Sekunden, aufgerundet auf das nächste Zeitfenster.
        Vorhanden bei Ablehnungen durch das Middleware-Budget.
      schema:
        type: integer
    BudgetXRateLimitScope:
      description: >-
        Der Geltungsbereich, dessen Budget überschritten wurde. Vorhanden bei
        Ablehnungen durch das Middleware-Budget.
      schema:
        type: string
    BudgetXRateLimitLimit:
      description: >-
        Budget für den überschrittenen Bereich; entspricht dem Limit im Body.
        Vorhanden bei Ablehnungen durch das Middleware-Budget.
      schema:
        type: integer
    BudgetXRateLimitRemaining:
      description: >-
        Verbleibendes Budget, auf null begrenzt. Entspricht remaining im Body.
        Bei Ablehnungen durch das Middleware-Budget vorhanden.
      schema:
        type: integer
    BudgetXRateLimitReset:
      description: >-
        Reset-Zeit in Unix-Sekunden; entspricht dem Body-Feld reset. Vorhanden
        bei Ablehnungen durch das Middleware-Budget.
      schema:
        type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Der API-Schlüssel Ihrer Anwendung, zu finden unter Developers -> API
        keys in der Business Console. Der primäre Schlüssel hat vollen Zugriff.
        Ein benannter Schlüssel kann eingeschränkt werden: pro Ressource keine,
        nur Lese- oder nur Schreibrechte, begrenzt auf einzelne Workflows oder
        nur auf genehmigte Sitzungen, auf eine Liste von IP-Adressen und auf ein
        Ablaufdatum. 401 bedeutet, dass der Schlüssel falsch, widerrufen oder
        abgelaufen ist. 403 bedeutet, dass kein Schlüssel gesendet wurde, der
        Schlüssel keinen Zugriff auf diese Ressource oder Aktion hat oder die
        Anfrage von einer Adresse außerhalb seiner IP-Liste kam. 404 bei einer
        Sitzungsroute bedeutet, dass die Sitzung außerhalb der Workflows oder
        Status des Schlüssels liegt. Ein Schlüssel ohne Medienzugriff erhält
        Bild-, Video- und PDF-URLs als null, und ein Schlüssel ohne
        Schreibzugriff auf Sitzungen erhält Sitzungslinks und Tokens als null.
        Siehe https://docs.didit.me/console/api-keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.