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

# API de llista de bancs: institucions i capacitats

> L'endpoint de Didit per llistar institucions retorna els bancs per país i el que admet cadascun: segments, accés continu, consentiment i més.

L'endpoint List Institutions de Didit retorna els bancs per país amb les funcionalitats que admet cadascun: segments, accés continu, durada del consentiment, profunditat de l'historial i els camps que envia.
Filtra per `country`, `segment`, `access` i `q`.
Consulta [Cobertura bancària](https://docs.didit.me/ca/core-technology/bank-verification/coverage.md).


## OpenAPI

````yaml ca/openapi-25.json GET /v3/bank/institutions/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API de verificació d'identitat. Autentica't amb la capçalera x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags:
  - name: Bank Data
    description: >-
      Bank Link, connexions, comptes, saldos, transaccions, entitats i
      cobertura. Les dades bancàries estan disponibles per a aplicacions en
      sandbox. Les crides d'una aplicació en producció responen `404` fins que
      s'anunciï l'accés en producció. No es cobra res en sandbox. Una crida feta
      amb una clau d'API necessita una clau que tingui el permís Bank data
      (`bank-data`): lectura per a les lectures, escriptura per a les operacions
      que canvien alguna cosa. La comprovació de comptes n'és l'excepció:
      necessita accés d'escriptura a sessions, o accés complet, i no el permís
      Bank data. Bank data no forma part de l'accés complet: una clau amb accés
      complet es rebutja, i la crida respon `403 bank_data_access_denied` fins
      que creïs una clau que tingui el permís. Les dades bancàries en brut
      (comptes, saldos, transaccions i el feed de canvis) també rebutgen una
      sol·licitud que no porti cap clau d'API.


      Cada rebuig sota `/v3/bank/` excepte el de la comprovació de comptes té el
      mateix cos JSON (`code`, `message`, `request_id`, `field`, `next_action`,
      `retry_after`). Un camí que no és una operació, un identificador que no és
      un UUID o un subrecurs desconegut respon `404 not_found` per a qualsevol
      mètode, i qualsevol error inesperat respon `500 internal_error` amb un
      `request_id`. Quan les dades bancàries no estan disponibles, cada operació
      respon el `404` estàndard de la plataforma, exactament com ho fa una ruta
      desconeguda.
paths:
  /v3/bank/institutions/:
    get:
      tags:
        - Bank Data
      summary: Llista les entitats financeres
      description: >-
        Llista els bancs per país amb les seves capacitats: segments, modes
        d'accés, el consentiment més llarg i l'historial més profund que ofereix
        el banc, si informa de les transaccions pendents, quins camps de
        transacció se sap que envia i com la persona inicia la sessió. Els
        valors provenen de dades observades i s'actualitzen cada dia; un valor
        mai observat és `null`. Les mateixes dades alimenten el selector de
        bancs, així que utilitza-les per saber què esperar abans de crear un
        enllaç. `access` només llista `ongoing` quan l'accés continu està
        disponible.


        Necessita una clau d'API amb el permís Bank data (`bank-data`): lectura
        per a aquesta operació. Una clau amb accés complet no l'inclou:
        concedeix-lo explícitament en crear la clau, o la crida respon `403
        bank_data_access_denied`.


        La llista s'ordena pel nom i després per identificador.


        En una aplicació sandbox, la llista conté el Didit Test Bank, un per
        cada país que serveix Bank Link, i cap banc real.
      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. If Bank Link
            does not serve this country, it answers `400 invalid_request` with
            `field: country`.
        - name: segment
          in: query
          required: false
          schema:
            type: string
            enum:
              - personal
              - business
          description: Només bancs que atenen aquest segment.
        - name: access
          in: query
          required: false
          schema:
            type: string
            enum:
              - one_time
              - ongoing
          description: Només bancs que ofereixen aquest mode d'accés.
        - name: q
          in: query
          required: false
          schema:
            type: string
            maxLength: 100
          description: Cerca per nom o id, sense distingir majúscules i minúscules.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 500
          description: Mida de pàgina, de 1 a 500. Per defecte, 100.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Cursor opac del `next_cursor` de la pàgina anterior.
      responses:
        '200':
          description: Una pàgina de bancs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankInstitutionList'
              examples:
                Spain, ongoing access:
                  summary: Un banc espanyol que ofereix accés continu
                  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: >-
            Un paràmetre no és vàlid, o `country` no és un país que Bank Link
            ofereixi. `field` indica quin és.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Invalid cursor:
                  summary: Cursor no vàlid
                  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: Sol·licitud no vàlida
                  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: >-
        Cos de l'error de cada operació de dades bancàries. Tots els camps hi
        són sempre presents.
      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: >-
            Codi d'error llegible per màquina. Decideix a partir d'aquest codi,
            mai a partir de `message`.
        message:
          type: string
          description: >-
            Explicació en llenguatge senzill per a un desenvolupador. La
            redacció pot canviar; no l'analitzis.
        request_id:
          type: string
          description: >-
            Identificador d'aquesta sol·licitud. Indica'l quan contactis amb el
            suport.
        field:
          type: string
          description: >-
            El camp de la sol·licitud que cal corregir, quan l'error fa
            referència a un sol camp. Altrament, `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: >-
            Què cal fer a continuació, perquè un client pugui actuar sense
            endevinar. `null` quan no hi ha un pas següent estàndard.
          nullable: true
        retry_after:
          type: integer
          description: >-
            Segons a esperar abans de reintentar. S'estableix en els errors de
            límit de freqüència i en els errors temporals; en cas contrari,
            `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: >-
        Un banc i el que admet. Els valors provenen de dades de capacitat
        observades, actualitzades cada dia; un valor mai observat és `null`, no
        una suposició.
      properties:
        id:
          type: string
          description: Identificador del banc de Didit, un slug estable.
          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: Fus horari IANA en què estan les dates del banc.
          nullable: true
        segments:
          type: array
          items:
            type: string
            enum:
              - personal
              - business
        access:
          type: array
          items:
            type: string
            enum:
              - one_time
              - ongoing
          description: >-
            `ongoing` només apareix en els bancs on l'accés continu està
            activat.
        ongoing_access:
          type: boolean
          description: Si hi ha accés continu disponible en aquest banc.
        consent_days_max:
          type: integer
          description: >-
            El consentiment més llarg que permet el banc, en dies. `null` quan
            no s'ha observat.
          nullable: true
        history_days_max:
          type: integer
          description: >-
            La història més profunda que lliura el banc, en dies. `null` quan no
            s'ha observat.
          nullable: true
        pending_transactions:
          type: boolean
          nullable: true
          description: Si el banc informa de les transaccions pendents.
        pending_linkage:
          type: boolean
          nullable: true
          description: >-
            Si el banc vincula una transacció pendent amb la seva
            comptabilitzada, que és el que defineix `pending_id`.
        balance_types:
          type: array
          items:
            type: string
            enum:
              - booked
              - available
              - expected
        transaction_fields:
          type: array
          items:
            type: string
          description: >-
            Els camps de transacció que se sap que el banc envia. La resta de
            camps són `null`.
        sign_in:
          type: string
          enum:
            - redirect
            - app_approval
            - credentials
            - null
          description: Com inicia la persona la sessió al banc.
          nullable: true
        requires_end_user_email:
          type: boolean
          nullable: true
          description: >-
            Si Bank Link necessita una adreça de correu electrònic verificada de
            la persona.
        corporate_accounts:
          type: boolean
          nullable: true
          description: Si s'admeten comptes d'empresa.
        bank_account_selection:
          type: boolean
          nullable: true
          description: >-
            Si la persona tria els comptes al banc en lloc de fer-ho a Bank
            Link.
        separate_history_consent:
          type: boolean
          nullable: true
          description: >-
            Si el banc demana una confirmació més per alliberar l'historial més
            antic.
        reconfirmation:
          type: boolean
          nullable: true
          description: >-
            Si una renovació es pot reconfirmar a la pantalla de Didit sense
            iniciar sessió al banc.
        sync_frequency_hours:
          type: integer
          description: >-
            Hores entre sincronitzacions automàtiques quan el banc permet una
            cadència més ràpida. `null` vol dir el valor diari per defecte.
          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: >-
        Només es retorna en un rebuig del pressupost del middleware de límit de
        freqüència. Altres errors 429, inclosos conflictes d'idempotència i
        límits específics de l'endpoint, no garanteixen aquests camps de
        metadades.
      required:
        - detail
        - reference
        - limit
        - remaining
        - reset
        - window_seconds
      properties:
        detail:
          type: string
          description: >-
            Missatge de denegació de pressupost existent, comprensible per a
            humans.
        reference:
          type: string
          pattern: ^RL-[0-9a-f]{32}$
          description: >-
            Referència de suport opaca: RL- seguit de 32 caràcters hexadecimals
            en minúscula d'un UUID.
        limit:
          type: integer
          description: Pressupost de l'àmbit superat; és igual a X-RateLimit-Limit.
        remaining:
          type: integer
          minimum: 0
          description: >-
            Pressupost restant, amb un mínim de zero; és igual que
            X-RateLimit-Remaining.
        reset:
          type: integer
          format: int64
          description: >-
            Temps de reinici de la finestra en segons Unix; és igual que
            X-RateLimit-Reset.
        window_seconds:
          type: integer
          description: >-
            Durada de la finestra fixa en segons, no l'espera restant. Respecta
            Retry-After abans de reintentar.
      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: No autoritzat
      content:
        application/json:
          examples:
            Invalid API Key:
              summary: Clau d'API no vàlida
              value:
                detail: Invalid API Key.
    BankDataAccessDenied:
      description: >-
        La clau d'API no té el permís Bank data (`bank-data`) o, per a dades
        bancàries sense processar en una aplicació de producció, la configuració
        de l'aplicació "Bank data in the API" està desactivada. Les dades
        bancàries no formen part de l'accés complet: una clau amb accés complet,
        una clau restringida a altres recursos i una sol·licitud autenticada
        sense clau d'API (credencials de client, sobre dades sense processar)
        són rebutjades amb aquest cos, així que crea una clau i concedeix-lo
        explícitament. El rebuig es produeix abans de cap cerca, de manera que
        no diu res sobre si un objecte existeix.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Bank data not allowed:
              summary: Dades bancàries no permeses
              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: >-
        S'ha superat el pressupost de lectura del middleware. Respecta
        Retry-After abans de reintentar.
      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: >-
        Hi ha hagut un error per part de Didit. Qualsevol error inesperat sota
        `/v3/bank/` respon amb el format d'error de Bank, mai amb una pàgina
        HTML: cita el `request_id` quan contactis amb el servei de suport.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Internal error:
              summary: Un error inesperat
              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: >-
        Nombre de segons que cal esperar, arrodonit fins a la finestra següent.
        Present en els rebutjos del pressupost del middleware.
      schema:
        type: integer
    BudgetXRateLimitScope:
      description: >-
        L'àmbit que ha superat el seu pressupost. Present en els rebutjos del
        pressupost del middleware.
      schema:
        type: string
    BudgetXRateLimitLimit:
      description: >-
        Pressupost de l'àmbit superat; és igual al límit del cos. Hi és present
        en les denegacions de pressupost del middleware.
      schema:
        type: integer
    BudgetXRateLimitRemaining:
      description: >-
        Pressupost restant, amb un mínim de zero; és igual que remaining del
        cos. Hi és present a les denegacions del pressupost del middleware.
      schema:
        type: integer
    BudgetXRateLimitReset:
      description: >-
        Temps de reinici en segons Unix; és igual que reset del cos. Present en
        els rebutjos del pressupost del middleware.
      schema:
        type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        La clau d'API de la teva aplicació, des de Developers -> API keys a la
        Business Console. La clau principal té accés complet. Una clau amb nom
        es pot limitar: cap, lectura o escriptura per recurs, limitada a alguns
        fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a
        una data de caducitat. 401 vol dir que la clau és incorrecta, revocada o
        caducada; 403 vol dir que no s'ha enviat cap clau, que la clau no té
        accés a aquest recurs o acció, o que la sol·licitud ve d'una adreça fora
        de la seva llista d'adreces IP; 404 en una ruta de sessió vol dir que la
        sessió queda fora dels fluxos de treball o estats de la clau. Una clau
        sense accés a multimèdia rep les URL d'imatges, vídeos i PDF com a null,
        i una clau sense escriptura de sessions rep els enllaços i els tokens de
        sessió com a null. Vegeu https://docs.didit.me/console/api-keys.

````

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