> ## 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.

# Get a Bank Connection API: Consent, Sync and Accounts

> Didit's Get a Bank Connection endpoint returns one connection with its status, consent dates, sync state, account summaries and cost.

Didit's Get a Bank Connection endpoint returns one connection with its status, consent dates, sync state, account summaries and cost.
`sync.initial_status` tells you when the first data is readable, `consent.expires_at` when to renew and `sync.budgets` how many refreshes the bank still allows.
See [Connections](https://docs.didit.me/core-technology/bank-verification/connections.md).


## OpenAPI

````yaml openapi-25.json GET /v3/bank/connections/{id}/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: Identity verification API. Authenticate with x-api-key header.
servers:
  - url: https://verification.didit.me
security: []
tags:
  - name: Bank Data
    description: >-
      Bank Link, connections, accounts, balances, transactions, institutions and
      coverage. Bank data is available for sandbox applications. A live
      application's calls answer `404` until live access is announced. Nothing
      is charged in sandbox. A call made with an API key needs a key that
      carries the Bank data permission (`bank-data`): read for reads, write for
      operations that change something. The account check is the exception: it
      needs write access to sessions, or full access, and not the Bank data
      permission. Bank data is not part of full access: a full-access key is
      refused, and the call answers `403 bank_data_access_denied` until you
      create a key that carries the permission. Raw bank data (accounts,
      balances, transactions and the change feed) also refuses a request that
      carries no API key.


      Every refusal under `/v3/bank/` except the account check's has the same
      JSON body (`code`, `message`, `request_id`, `field`, `next_action`,
      `retry_after`). A path that is not an operation, an id that is not a UUID
      or an unknown sub-resource answers `404 not_found` for every method, and
      any unexpected error answers `500 internal_error` with a `request_id`.
      Where Bank data is not available, every operation answers the platform's
      standard `404`, exactly as an unknown route does.
paths:
  /v3/bank/connections/{id}/:
    get:
      tags:
        - Bank Data
      summary: Get a bank connection
      description: >-
        Returns the connection with its consent, sync state and a summary of
        each account. Read the data itself with the accounts, balances and
        transactions operations. A connection that was deleted reads as a
        minimal record: its id, `status: deleted`, the reason, its dates and its
        `erasure` status, and no accounts, balances, transactions, consent or
        sync data.


        Needs an API key with the Bank data permission (`bank-data`): read for
        this operation. A key with full access does not include it: grant it
        explicitly when you create the key, or the call answers `403
        bank_data_access_denied`.
      operationId: getBankConnection
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The connection id.
      responses:
        '200':
          description: The connection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankConnection'
              examples:
                Active ongoing connection:
                  summary: An active ongoing business connection
                  value:
                    id: 5e1d2a70-3b94-4c1f-8a6e-d2f07b9c1e35
                    environment: live
                    access: ongoing
                    status: active
                    status_reason: null
                    institution:
                      id: es-banco-norte
                      name: Banco Norte
                      country: ESP
                      logo_url: https://static.example.com/banks/es-banco-norte.png
                    segment: business
                    data:
                      - accounts
                      - balances
                      - transactions
                    consent:
                      status: granted
                      version: 1
                      granted_at: '2026-11-21T12:04:11Z'
                      expires_at: '2027-05-20T12:04:11Z'
                      days_granted: 180
                      renewed_count: 0
                      scopes_requested:
                        - accounts
                        - balances
                        - transactions
                      scopes_granted:
                        - accounts
                        - balances
                        - transactions
                      accounts_granted:
                        - a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10
                        - c3d84e19-2a7b-4f60-b5e1-9a0c6d3f8e72
                      renewal_action: bank_auth
                      renew_by: '2027-05-20T12:04:11Z'
                      reconfirm_by: null
                      renewable_until: null
                      retain_until: null
                      ended_at: null
                      ended_by: null
                    sync:
                      status: ok
                      initial_status: succeeded
                      initial_complete: true
                      history_complete: true
                      last_synced_at: '2026-11-21T12:04:40Z'
                      next_sync_at: '2026-11-22T06:00:00Z'
                      budgets:
                        - scope: connection
                          resource: all
                          limit: 4
                          remaining: 3
                          resets_at: '2026-11-22T00:00:00Z'
                      last_error: null
                      frequency_per_day: 1
                      live_syncs_left_today: 3
                    accounts:
                      - id: a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10
                        name: Cuenta negocio
                        type: current
                        usage: business
                        currency: EUR
                        iban_last4: '1332'
                        status: open
                      - id: c3d84e19-2a7b-4f60-b5e1-9a0c6d3f8e72
                        name: Cuenta de ahorro
                        type: savings
                        usage: business
                        currency: EUR
                        iban_last4: '7708'
                        status: open
                    ownership:
                      compare: none
                      match: null
                      check_id: null
                      result: null
                    end_user:
                      reference: client-7731
                    manage_url: null
                    billing:
                      unit: connection_month
                      price_usd: '0.9000'
                      billed_through: '2026-11-30'
                    possible_duplicate_of: null
                    erasure: null
                    vendor_data: client-7731
                    created_at: '2026-11-21T12:03:02Z'
                    updated_at: '2026-11-21T12:04:40Z'
                Renewal required:
                  summary: The consent ended; data stays readable as last synced
                  value:
                    id: 5e1d2a70-3b94-4c1f-8a6e-d2f07b9c1e35
                    environment: live
                    access: ongoing
                    status: renewal_required
                    status_reason: consent_expired
                    institution:
                      id: es-banco-norte
                      name: Banco Norte
                      country: ESP
                      logo_url: https://static.example.com/banks/es-banco-norte.png
                    segment: business
                    data:
                      - accounts
                      - balances
                      - transactions
                    consent:
                      status: expired
                      version: 1
                      granted_at: '2026-11-21T12:04:11Z'
                      expires_at: '2027-05-20T12:04:11Z'
                      days_granted: 180
                      renewed_count: 0
                      scopes_requested:
                        - accounts
                        - balances
                        - transactions
                      scopes_granted:
                        - accounts
                        - balances
                        - transactions
                      accounts_granted:
                        - a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10
                        - c3d84e19-2a7b-4f60-b5e1-9a0c6d3f8e72
                      renewal_action: bank_auth
                      renew_by: '2027-05-20T12:04:11Z'
                      reconfirm_by: null
                      renewable_until: '2027-06-19T12:04:11Z'
                      retain_until: '2027-06-19T12:04:11Z'
                      ended_at: '2027-05-20T12:04:11Z'
                      ended_by: bank
                    sync:
                      status: ok
                      initial_status: succeeded
                      initial_complete: true
                      history_complete: true
                      last_synced_at: '2026-11-21T12:04:40Z'
                      next_sync_at: '2026-11-22T06:00:00Z'
                      budgets:
                        - scope: connection
                          resource: all
                          limit: 4
                          remaining: 3
                          resets_at: '2026-11-22T00:00:00Z'
                      last_error: null
                      frequency_per_day: 1
                      live_syncs_left_today: 3
                    accounts:
                      - id: a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10
                        name: Cuenta negocio
                        type: current
                        usage: business
                        currency: EUR
                        iban_last4: '1332'
                        status: open
                      - id: c3d84e19-2a7b-4f60-b5e1-9a0c6d3f8e72
                        name: Cuenta de ahorro
                        type: savings
                        usage: business
                        currency: EUR
                        iban_last4: '7708'
                        status: open
                    ownership:
                      compare: none
                      match: null
                      check_id: null
                      result: null
                    end_user:
                      reference: client-7731
                    manage_url: null
                    billing:
                      unit: connection_month
                      price_usd: '0.9000'
                      billed_through: '2026-11-30'
                    possible_duplicate_of: null
                    erasure: null
                    vendor_data: client-7731
                    created_at: '2026-11-21T12:03:02Z'
                    updated_at: '2026-11-21T12:04:40Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BankDataAccessDenied'
        '404':
          description: The resource does not exist in this application and environment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Not found:
                  summary: Not found
                  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/RateLimitedRead'
        '500':
          $ref: '#/components/responses/BankDataInternalError'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: >-
            curl
            'https://verification.didit.me/v3/bank/connections/5e1d2a70-3b94-4c1f-8a6e-d2f07b9c1e35/'
            \
              -H 'x-api-key: YOUR_API_KEY'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.bank.get_connection(
                "11111111-2222-3333-4444-555555555555",
            )
            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.getConnection("11111111-2222-3333-4444-555555555555");

            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Bank.GetConnection(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: >-
            import me.didit.Didit;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.bank().getConnection("11111111-2222-3333-4444-555555555555");

            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->getConnection('11111111-2222-3333-4444-555555555555');

            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: >-
            require "didit"


            # Reads DIDIT_API_KEY.

            didit = Didit::Client.new


            result =
            didit.bank.get_connection("11111111-2222-3333-4444-555555555555")

            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.GetConnectionAsync("11111111-2222-3333-4444-555555555555");

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    BankConnection:
      type: object
      description: >-
        The person's permission for your application to read one bank. A renewal
        keeps the connection id and every account id. A deleted connection
        answers only `id`, `status`, `status_reason`, `created_at` and
        `erasure`: every other field is absent, and no bank, person or account
        data remains in it.
      properties:
        id:
          type: string
          description: Identifier of the connection.
          format: uuid
        environment:
          type: string
          enum:
            - live
            - sandbox
        access:
          type: string
          enum:
            - one_time
            - ongoing
        status:
          type: string
          enum:
            - pending
            - active
            - renewal_required
            - paused
            - revoked
            - deleted
            - failed
          description: >-
            `pending`: first sync running. `active`: consent valid.
            `renewal_required`: the consent ended or the bank wants the person
            to sign in again, data readable as last synced and nothing charged.
            `paused`: balance too low for the month. `revoked`: access stopped
            by the person, the bank or you. `deleted`: only `id`, `status`,
            `status_reason`, `created_at` and `erasure` remain. `failed`: the
            first sync never succeeded.
        status_reason:
          type: string
          enum:
            - collection_complete
            - consent_expired
            - consent_lapsed
            - bank_requires_sign_in
            - revoked_by_end_user
            - revoked_by_bank
            - revoked_by_customer
            - insufficient_balance
            - paused_by_customer
            - first_sync_failed
            - deleted_by_customer
            - retention_elapsed
            - application_deleted
            - null
          description: >-
            Why the connection is in this status. `paused_by_customer` is
            reserved. On a `deleted` connection: `deleted_by_customer`,
            `consent_lapsed`, `retention_elapsed` or `application_deleted`.
          nullable: true
        institution:
          $ref: '#/components/schemas/BankInstitutionSummary'
        segment:
          type: string
          enum:
            - personal
            - business
            - null
          nullable: true
        data:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
          description: The scopes the person accepted.
        consent:
          $ref: '#/components/schemas/BankConnectionConsent'
        sync:
          $ref: '#/components/schemas/BankConnectionSync'
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/BankConnectionAccountSummary'
          description: >-
            Summary of every account in the connection. Read the full account
            with `get_account`.
        ownership:
          $ref: '#/components/schemas/BankConnectionOwnership'
        end_user:
          type: object
          properties:
            reference:
              type: string
              description: Your id for the person or company.
              nullable: true
          required:
            - reference
        manage_url:
          type: string
          description: >-
            The person's own access page. `null` until the access page is
            available.
          nullable: true
          format: uri
        billing:
          $ref: '#/components/schemas/BankConnectionBilling'
        possible_duplicate_of:
          type: string
          description: >-
            Set when this connection may duplicate another active one but no
            `end_user.reference` allowed a certain match.
          format: uuid
          nullable: true
        erasure:
          allOf:
            - $ref: '#/components/schemas/BankConnectionErasure'
          nullable: true
          description: Set after `delete_connection`; otherwise `null`.
        vendor_data:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - status
        - status_reason
        - created_at
        - erasure
    BankDataError:
      type: object
      description: Error body of every Bank data operation. Every field is always present.
      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: Machine-readable error code. Branch on this, never on `message`.
        message:
          type: string
          description: >-
            Plain-language explanation for a developer. The wording can change;
            do not parse it.
        request_id:
          type: string
          description: Identifier of this request. Quote it when you contact support.
        field:
          type: string
          description: >-
            The request field to correct, when the error is about one field.
            Otherwise `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: >-
            What to do next, so a client can act without guessing. `null` when
            there is no standard next step.
          nullable: true
        retry_after:
          type: integer
          description: >-
            Seconds to wait before retrying. Set on rate-limit and temporary
            errors, otherwise `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
    BankInstitutionSummary:
      type: object
      description: The bank a connection or link is for.
      properties:
        id:
          type: string
          description: >-
            Didit's identifier of the bank, a stable slug. Use it as
            `institution_id`.
          example: es-banco-norte
        name:
          type: string
          description: The bank's name.
          example: Banco Norte
        country:
          type: string
          description: Country of the bank, ISO 3166-1 alpha-3.
          pattern: ^[A-Z]{3}$
          example: ESP
        logo_url:
          type: string
          description: Logo of the bank, or `null`.
          nullable: true
          format: uri
      required:
        - id
        - name
        - country
        - logo_url
    BankConnectionConsent:
      type: object
      description: The person's consent for this connection.
      properties:
        status:
          type: string
          enum:
            - granted
            - expired
            - revocation_pending
            - revoked
            - revocation_failed
          description: >-
            `revocation_pending` until the bank confirms the consent is
            terminated, then `revoked`. `revocation_failed` is retried
            automatically. Bank fetches stop the moment a revocation is
            requested.
        version:
          type: integer
          description: >-
            Version of the consent. A renewal creates the next version on the
            same connection.
        granted_at:
          type: string
          format: date-time
          nullable: true
        expires_at:
          type: string
          description: >-
            When the bank's consent ends. The bank sets it, up to
            `consent_days`.
          format: date-time
          nullable: true
        days_granted:
          type: integer
          description: Length of the consent in days, as the bank granted it.
          nullable: true
        renewed_count:
          type: integer
          description: How many times the consent was renewed.
        scopes_requested:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
        scopes_granted:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
        accounts_granted:
          type: array
          items:
            type: string
            format: uuid
          description: Ids of the accounts the person shares.
        renewal_action:
          type: string
          enum:
            - reconfirm
            - bank_auth
            - null
          description: >-
            How a renewal works: `reconfirm` is the person confirming on Didit's
            screen with no bank sign-in, where the bank and the country's rules
            allow it. `bank_auth` is a bank sign-in.
          nullable: true
        renew_by:
          type: string
          description: 'The consent''s end: renew before it for no gap.'
          format: date-time
          nullable: true
        reconfirm_by:
          type: string
          description: >-
            Set when `renewal_action` is `reconfirm`: the last moment to
            reconfirm.
          format: date-time
          nullable: true
        renewable_until:
          type: string
          description: >-
            The last moment the same connection can be revived after the consent
            ended. After it the person connects again. It equals `retain_until`.
          format: date-time
          nullable: true
        retain_until:
          type: string
          description: >-
            Set once access ended: how long the stored data stays readable, set
            by the retention setting of your application.
          format: date-time
          nullable: true
        ended_at:
          type: string
          format: date-time
          nullable: true
        ended_by:
          type: string
          enum:
            - end_user
            - bank
            - customer
            - unknown
            - null
          description: >-
            Who ended access, set from evidence. `unknown` when neither the bank
            nor the sync says.
          nullable: true
      required:
        - status
        - version
        - granted_at
        - expires_at
        - days_granted
        - renewed_count
        - scopes_requested
        - scopes_granted
        - accounts_granted
        - renewal_action
        - renew_by
        - reconfirm_by
        - renewable_until
        - retain_until
        - ended_at
        - ended_by
    BankConnectionSync:
      type: object
      description: Synchronisation state of a connection.
      properties:
        status:
          type: string
          enum:
            - pending
            - ok
            - failing
          description: >-
            `failing` after 24 hours of failed attempts, which are retried with
            backoff. A bank that asks the person to sign in again makes the
            connection `renewal_required` instead.
        initial_status:
          type: string
          enum:
            - pending
            - succeeded
            - partial
            - failed
          description: >-
            Result of the first sync. The connection becomes `active` on
            `succeeded` or `partial`, and `failed` when no account succeeded.
        initial_complete:
          type: boolean
          description: >-
            `true` only when `initial_status` is `succeeded`: accounts, balances
            and recent transactions are readable.
        history_complete:
          type: boolean
          description: >-
            `true` when the history backfill ended, for any reason. Ranges it
            could not get are in each account's
            `history_coverage.missing_ranges`.
        last_synced_at:
          type: string
          description: When data was last fetched from the bank, not when you last read it.
          format: date-time
          nullable: true
        next_sync_at:
          type: string
          description: >-
            When the next automatic sync is planned. The automatic sync runs
            between one and four times a day depending on the bank (see
            `frequency_per_day`).
          format: date-time
          nullable: true
        budgets:
          type: array
          items:
            $ref: '#/components/schemas/BankSyncBudget'
          description: The bank's limits on fetches without the person present.
        last_error:
          allOf:
            - $ref: '#/components/schemas/BankSyncError'
          nullable: true
          description: The last sync error, or `null`.
        frequency_per_day:
          type: integer
          minimum: 1
          maximum: 4
          description: >-
            How many times a day the automatic sync runs for this connection,
            between one and four depending on the bank. Where the bank allows
            more unattended reads, at least two a day always remain for live
            syncs.
        live_syncs_left_today:
          type: integer
          minimum: 0
          description: >-
            How many live syncs (`refresh_connection`) are left today within the
            bank's limit: the tightest budget's `remaining`. `null` where the
            bank sets no limit. Live syncs are included in the monthly price.
          nullable: true
      required:
        - status
        - initial_status
        - initial_complete
        - history_complete
        - last_synced_at
        - next_sync_at
        - budgets
        - last_error
        - frequency_per_day
        - live_syncs_left_today
    BankConnectionAccountSummary:
      type: object
      description: Short form of an account inside a connection.
      properties:
        id:
          type: string
          description: >-
            Account id. Stable for the life of the connection, renewals
            included.
          format: uuid
        name:
          type: string
          nullable: true
        type:
          type: string
          enum:
            - current
            - savings
            - card
            - loan
            - investment
            - other
        usage:
          type: string
          enum:
            - personal
            - business
            - unknown
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: ISO 4217 currency code.
        iban_last4:
          type: string
          description: Last four characters of the IBAN, where the account has one.
          nullable: true
        status:
          type: string
          enum:
            - open
            - closed
            - access_removed
      required:
        - id
        - name
        - type
        - usage
        - currency
        - iban_last4
        - status
    BankConnectionOwnership:
      type: object
      description: The optional comparison of the account holder with a person or company.
      properties:
        compare:
          type: string
          enum:
            - none
            - person
            - business
        match:
          type: string
          enum:
            - any_holder
            - all_holders
            - null
          nullable: true
        check_id:
          type: string
          description: Id of the ownership result when a comparison was asked.
          format: uuid
          nullable: true
        result:
          type: string
          enum:
            - match
            - close_match
            - no_match
            - unknown
            - null
          description: >-
            Verdict. `unknown` whenever missing holder evidence could change it,
            and when the bank shares no holder.
          nullable: true
      required:
        - compare
        - match
        - check_id
        - result
    BankConnectionBilling:
      type: object
      description: What this connection costs. Sandbox is never charged.
      properties:
        unit:
          type: string
          description: >-
            Billing unit, `connection_month` for ongoing access, `one_time`
            otherwise.
          enum:
            - connection_month
            - one_time
        price_usd:
          type: string
          description: >-
            Your price for the month meter today, for your application and the
            country, in USD, a decimal string with 4 decimals. A connection is
            charged for a month only when every accepted scope published data
            for at least one account in that month. `null` for one-time
            connections and in the sandbox. Ongoing access is billed per active
            connection per month; the current price is on the pricing page
            (https://docs.didit.me/getting-started/pricing). Amounts in examples
            are illustrative; the price for a country is shown on the pricing
            page.
          pattern: ^-?\d+(\.\d+)?$
          nullable: true
        billed_through:
          type: string
          description: The last month end already settled.
          format: date
          nullable: true
      required:
        - unit
        - price_usd
        - billed_through
    BankConnectionErasure:
      type: object
      description: >-
        The record of a deletion you asked for. The deletion itself is
        immediate: the connection's data is deleted and unreadable when the call
        returns. `status` is the confirmation of it.
      properties:
        status:
          type: string
          enum:
            - pending
            - erased
            - failed
          description: >-
            The confirmation of the deletion. `pending`: the deletion is being
            confirmed, including the end of access at the bank. `erased`:
            confirmed, with `erased_at`. `failed`: the confirmation has not
            arrived yet and is repeated automatically; nothing is needed from
            you. The data is deleted and not readable in any of the three.
        requested_at:
          type: string
          format: date-time
          description: When you asked for the deletion.
        erased_at:
          type: string
          format: date-time
          nullable: true
          description: When the deletion was confirmed. `null` until `status` is `erased`.
      required:
        - status
        - requested_at
        - erased_at
    RateLimitBudgetError:
      type: object
      description: >-
        Returned only for a rate-limit middleware budget refusal. Other 429
        errors, including idempotency conflicts and endpoint-specific caps, do
        not promise these metadata fields.
      required:
        - detail
        - reference
        - limit
        - remaining
        - reset
        - window_seconds
      properties:
        detail:
          type: string
          description: Existing human-readable budget refusal message.
        reference:
          type: string
          pattern: ^RL-[0-9a-f]{32}$
          description: >-
            Opaque support reference: RL- followed by 32 lowercase UUID
            hexadecimal characters.
        limit:
          type: integer
          description: Budget for the exceeded scope; equals X-RateLimit-Limit.
        remaining:
          type: integer
          minimum: 0
          description: Remaining budget, clamped to zero; equals X-RateLimit-Remaining.
        reset:
          type: integer
          format: int64
          description: Window reset time in Unix seconds; equals X-RateLimit-Reset.
        window_seconds:
          type: integer
          description: >-
            Fixed-window duration in seconds, not the remaining wait. Honor
            Retry-After before retrying.
      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
    BankSyncBudget:
      type: object
      description: One bucket of the bank's limit on fetches without the person present.
      properties:
        scope:
          type: string
          enum:
            - connection
            - account
          description: What the bank counts the budget against.
        resource:
          type: string
          enum:
            - all
            - accounts
            - balances
            - transactions
        account_id:
          type: string
          description: The account, when `scope` is `account`.
          format: uuid
          nullable: true
        limit:
          type: integer
          description: >-
            How many times a day Didit may fetch from the bank without the
            person present, as the bank defines it. This is a ceiling set by the
            bank, not a promise.
        remaining:
          type: integer
          description: >-
            Fetches left for your refreshes in the current window. The reads
            kept for the automatic syncs are already taken out, and an automatic
            sync never takes the last two reads of the day, so two refreshes on
            demand always remain.
        resets_at:
          type: string
          description: When the window resets.
          format: date-time
      required:
        - scope
        - resource
        - limit
        - remaining
        - resets_at
    BankSyncError:
      type: object
      description: Why a sync failed.
      properties:
        code:
          type: string
          description: Didit error code.
        message:
          type: string
          description: Plain-language explanation.
        at:
          type: string
          description: When it happened. `null` on a per-account result.
          format: date-time
          nullable: true
      required:
        - code
        - message
        - at
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          examples:
            Invalid API Key:
              summary: Invalid API Key
              value:
                detail: Invalid API Key.
    BankDataAccessDenied:
      description: >-
        The API key does not carry the Bank data permission (`bank-data`), or,
        for raw bank data in a live application, the application setting "Bank
        data in the API" is off. Bank data is not part of full access: a
        full-access key, a key restricted to other resources and a request
        authenticated without an API key (client credentials, on raw data) are
        all refused with this body, so create a key and grant it explicitly. The
        refusal comes before any lookup, so it says nothing about whether an
        object exists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Bank data not allowed:
              summary: Bank data not allowed
              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
    RateLimitedRead:
      description: Middleware read budget exceeded. Honor Retry-After before retrying.
      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'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitBudgetError'
          example:
            detail: >-
              GET request rate limit exceeded. You can make up to 600 requests
              per minute.
            reference: RL-00000000000040008000000000000001
            limit: 600
            remaining: 0
            reset: 1794358860
            window_seconds: 60
    BankDataInternalError:
      description: >-
        Something went wrong on Didit's side. Any unexpected error under
        `/v3/bank/` answers in the Bank error shape, never an HTML page: quote
        `request_id` to support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Internal error:
              summary: An unexpected error
              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: >-
        Seconds to wait, rounded up to the next window. Present on middleware
        budget refusals.
      schema:
        type: integer
    BudgetXRateLimitScope:
      description: >-
        The scope whose budget was exceeded. Present on middleware budget
        refusals.
      schema:
        type: string
    BudgetXRateLimitLimit:
      description: >-
        Budget for the exceeded scope; equals body limit. Present on middleware
        budget refusals.
      schema:
        type: integer
    BudgetXRateLimitRemaining:
      description: >-
        Remaining budget, clamped to zero; equals body remaining. Present on
        middleware budget refusals.
      schema:
        type: integer
    BudgetXRateLimitReset:
      description: >-
        Reset time in Unix seconds; equals body reset. Present on middleware
        budget refusals.
      schema:
        type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your application's API key, from Developers -> API keys in the Business
        Console. The primary key has full access. A named key can be scoped:
        none, read or write per resource, limited to some workflows or to
        approved sessions, to a list of IP addresses, and to an expiry date. 401
        means the key is wrong, revoked or expired; 403 means no key was sent,
        the key has no access to this resource or action, or the request came
        from an address outside its IP list; 404 on a session route means the
        session is outside the key's workflows or statuses. A key without media
        access receives image, video and PDF URLs as null, and a key without
        sessions write receives session links and tokens as null. See
        https://docs.didit.me/console/api-keys.

````

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