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

# List Banks API: Institutions and Capabilities

> Didit's List Institutions endpoint returns banks per country with what each supports: segments, ongoing access, consent length, history depth and the fields...

Didit's List Institutions endpoint returns banks per country with what each supports: segments, ongoing access, consent length, history depth and the fields it sends.
Filter by `country`, `segment`, `access` and `q`.
See [Bank coverage](https://docs.didit.me/core-technology/bank-verification/coverage.md).


## OpenAPI

````yaml openapi-25.json GET /v3/bank/institutions/
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/institutions/:
    get:
      tags:
        - Bank Data
      summary: List institutions
      description: >-
        Lists the banks per country with their capabilities: segments, access
        modes, the longest consent and deepest history the bank offers, whether
        it reports pending transactions, which transaction fields it is known to
        send, and how the person signs in. Values come from observed data,
        refreshed daily; a value never observed is `null`. The same data feeds
        the bank picker, so use it to know what to expect before you create a
        link. `access` lists `ongoing` only where ongoing access is available.


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


        The list is sorted by name, then id.


        In a sandbox application the list holds the Didit Test Bank, one per
        country Bank Link serves, and no live bank.
      operationId: listBankInstitutions
      parameters:
        - name: country
          in: query
          required: false
          schema:
            type: string
            pattern: ^[A-Z]{3}$
          description: >-
            Only banks in this country, an ISO 3166-1 alpha-3 code. A country
            Bank Link does not serve answers `400 invalid_request` with `field:
            country`.
        - name: segment
          in: query
          required: false
          schema:
            type: string
            enum:
              - personal
              - business
          description: Only banks that serve this segment.
        - name: access
          in: query
          required: false
          schema:
            type: string
            enum:
              - one_time
              - ongoing
          description: Only banks that offer this access mode.
        - name: q
          in: query
          required: false
          schema:
            type: string
            maxLength: 100
          description: Search by name or id, case-insensitive.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 500
          description: Page size, 1 to 500. Default 100.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Opaque cursor from the previous page's `next_cursor`.
      responses:
        '200':
          description: A page of banks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankInstitutionList'
              examples:
                Spain, ongoing access:
                  summary: A Spanish bank that offers ongoing access
                  value:
                    items:
                      - id: es-banco-norte
                        name: Banco Norte
                        country: ESP
                        logo_url: https://static.example.com/banks/es-banco-norte.png
                        timezone: Europe/Madrid
                        segments:
                          - personal
                          - business
                        access:
                          - one_time
                          - ongoing
                        ongoing_access: true
                        consent_days_max: 180
                        history_days_max: 365
                        pending_transactions: true
                        pending_linkage: false
                        balance_types:
                          - booked
                          - available
                        transaction_fields:
                          - value_date
                          - counterparty_name
                          - counterparty_iban
                          - remittance
                          - bank_transaction_code
                          - bank_reference
                          - balance_after
                        sign_in: redirect
                        requires_end_user_email: true
                        corporate_accounts: true
                        bank_account_selection: false
                        separate_history_consent: false
                        reconfirmation: false
                        sync_frequency_hours: null
                        health: operational
                    next_cursor: null
        '400':
          description: >-
            A parameter is invalid, or `country` is not a country Bank Link
            serves. `field` names it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Invalid cursor:
                  summary: Invalid cursor
                  value:
                    code: invalid_cursor
                    message: The cursor or page token is not valid.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: cursor
                    next_action: null
                    retry_after: null
                Invalid request:
                  summary: Invalid request
                  value:
                    code: invalid_request
                    message: The request is not valid.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: limit
                    next_action: null
                    retry_after: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BankDataAccessDenied'
        '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/institutions/?country=ESP&segment=business&access=ongoing'
            \
              -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.list_institutions()
            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.listInstitutions();
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Bank.ListInstitutions(ctx, didit.BankListInstitutionsParams{})\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().listInstitutions();
            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->listInstitutions();
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

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

            result = didit.bank.list_institutions
            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.ListInstitutionsAsync();
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    BankInstitutionList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BankInstitution'
        next_cursor:
          type: string
          nullable: true
      required:
        - items
        - next_cursor
    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
    BankInstitution:
      type: object
      description: >-
        A bank and what it supports. Values come from observed capability data,
        refreshed daily; a value never observed is `null`, not a guess.
      properties:
        id:
          type: string
          description: Didit's identifier of the bank, a stable slug.
          example: es-banco-norte
        name:
          type: string
        country:
          type: string
          pattern: ^[A-Z]{3}$
        logo_url:
          type: string
          format: uri
          nullable: true
        timezone:
          type: string
          description: IANA time zone the bank's dates are in.
          nullable: true
        segments:
          type: array
          items:
            type: string
            enum:
              - personal
              - business
        access:
          type: array
          items:
            type: string
            enum:
              - one_time
              - ongoing
          description: >-
            `ongoing` is listed only where ongoing access is switched on for the
            bank.
        ongoing_access:
          type: boolean
          description: Whether ongoing access is available at this bank.
        consent_days_max:
          type: integer
          description: >-
            The longest consent the bank allows, in days. `null` when not
            observed.
          nullable: true
        history_days_max:
          type: integer
          description: >-
            The deepest history the bank delivers, in days. `null` when not
            observed.
          nullable: true
        pending_transactions:
          type: boolean
          nullable: true
          description: Whether the bank reports pending transactions.
        pending_linkage:
          type: boolean
          nullable: true
          description: >-
            Whether the bank links a pending transaction to its booked one,
            which is what sets `pending_id`.
        balance_types:
          type: array
          items:
            type: string
            enum:
              - booked
              - available
              - expected
        transaction_fields:
          type: array
          items:
            type: string
          description: >-
            The transaction fields the bank is known to send. Every other field
            is `null`.
        sign_in:
          type: string
          enum:
            - redirect
            - app_approval
            - credentials
            - null
          description: How the person signs in at the bank.
          nullable: true
        requires_end_user_email:
          type: boolean
          nullable: true
          description: Whether Bank Link needs a verified email address for the person.
        corporate_accounts:
          type: boolean
          nullable: true
          description: Whether business accounts are supported.
        bank_account_selection:
          type: boolean
          nullable: true
          description: >-
            Whether the person picks the accounts at the bank instead of in Bank
            Link.
        separate_history_consent:
          type: boolean
          nullable: true
          description: >-
            Whether the bank asks for one more confirmation to release older
            history.
        reconfirmation:
          type: boolean
          nullable: true
          description: >-
            Whether a renewal can be reconfirmed on Didit's screen without a
            bank sign-in.
        sync_frequency_hours:
          type: integer
          description: >-
            Hours between automatic syncs where the bank allows a faster
            cadence. `null` means the daily default.
          nullable: true
        health:
          type: string
          enum:
            - operational
            - degraded
            - down
      required:
        - id
        - name
        - country
        - logo_url
        - timezone
        - segments
        - access
        - ongoing_access
        - consent_days_max
        - history_days_max
        - pending_transactions
        - pending_linkage
        - balance_types
        - transaction_fields
        - sign_in
        - requires_end_user_email
        - corporate_accounts
        - bank_account_selection
        - separate_history_consent
        - reconfirmation
        - sync_frequency_hours
        - health
    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
  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.