> ## 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 per ottenere un conto bancario: identificativi, titolari e sincronizzazione

> L'endpoint Get an Account di Didit restituisce un conto con identificativi, titolari, stato di sincronizzazione e copertura dello storico.

L'endpoint Get an Account di Didit restituisce un singolo conto con i suoi identificativi, i titolari, lo stato di aggiornamento della sincronizzazione e la copertura dello storico.
`sync.last_synced_at` indica quando Didit ha recuperato per l'ultima volta i dati dalla banca.
Per visualizzare gli identificativi completi è necessaria l'autorizzazione per i dati bancari sulla tua chiave API.
Consulta [Conti, saldi e transazioni](https://docs.didit.me/it/core-technology/bank-verification/accounts-balances-transactions.md).


## OpenAPI

````yaml it/openapi-25.json GET /v3/bank/accounts/{account_id}/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API di verifica dell'identità. Autenticati con l'header x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags:
  - name: Bank Data
    description: >-
      Bank Link, connessioni, conti, saldi, transazioni, istituti e copertura. I
      dati bancari sono disponibili per le applicazioni sandbox. Le chiamate di
      un'applicazione in produzione restituiscono `404` finché l'accesso di
      produzione non viene annunciato. Nel sandbox non viene addebitato nulla.
      Una chiamata effettuata con una chiave API richiede una chiave che abbia
      l'autorizzazione dati bancari (`bank-data`): lettura per le letture,
      scrittura per le operazioni che modificano qualcosa. Il controllo del
      conto fa eccezione: richiede accesso in scrittura alle sessioni, oppure
      accesso completo, e non l'autorizzazione dati bancari. I dati bancari non
      fanno parte dell'accesso completo: una chiave con accesso completo viene
      rifiutata e la chiamata risponde `403 bank_data_access_denied` finché non
      crei una chiave che abbia l'autorizzazione. I dati bancari grezzi (conti,
      saldi, transazioni e flusso delle modifiche) rifiutano anche una richiesta
      che non contiene una chiave API.


      Ogni rifiuto sotto `/v3/bank/`, eccetto quello del controllo del conto, ha
      lo stesso corpo JSON (`code`, `message`, `request_id`, `field`,
      `next_action`, `retry_after`). Un percorso che non è un'operazione, un ID
      che non è un UUID o una sotto-risorsa sconosciuta risponde `404 not_found`
      per ogni metodo, e qualsiasi errore imprevisto risponde `500
      internal_error` con un `request_id`. Dove i dati bancari non sono
      disponibili, ogni operazione risponde con il `404` standard della
      piattaforma, esattamente come fa un percorso sconosciuto.
paths:
  /v3/bank/accounts/{account_id}/:
    get:
      tags:
        - Bank Data
      summary: Ottieni un conto
      description: >-
        Restituisce un conto con identificativi completi, intestatari, stato
        della sincronizzazione e `history_coverage`, che indica cosa la banca ha
        fornito dello storico richiesto. `sync.last_synced_at` indica quando i
        dati sono stati recuperati dalla banca, non quando li leggi.


        Richiede una chiave API con l'autorizzazione Bank data (`bank-data`):
        lettura per questa operazione. Una chiave con accesso completo non la
        include: concedila esplicitamente quando crei la chiave, altrimenti la
        chiamata risponde `403 bank_data_access_denied`. Un'applicazione sandbox
        legge i dati bancari di test con la sola chiave. Una richiesta senza
        chiave API (credenziali client) viene rifiutata sui dati grezzi con lo
        stesso `403`.
      operationId: getBankAccount
      parameters:
        - name: account_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: L'id del conto.
      responses:
        '200':
          description: Il conto.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
              examples:
                Business account:
                  summary: Un conto corrente aziendale in Spagna
                  value:
                    id: a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10
                    connection_id: 5e1d2a70-3b94-4c1f-8a6e-d2f07b9c1e35
                    name: Cuenta negocio
                    product: Cuenta corriente empresas
                    type: current
                    usage: business
                    currency: EUR
                    holder_name: EMPRESA DE EJEMPLO SL
                    holders:
                      - name: EMPRESA DE EJEMPLO SL
                        role: holder
                    identifiers:
                      iban: ES0000000000000000001332
                      bic: XXXXESBBXXX
                      account_number: null
                      sort_code: null
                      other: []
                    account_ref: ar_f3c1a85e9d27b640c8e1
                    account_ref_previous: null
                    status: open
                    scopes_granted:
                      - accounts
                      - balances
                      - transactions
                    sync:
                      last_synced_at: '2026-11-21T12:04:40Z'
                      status: ok
                      history_requested_from: '2025-11-21'
                      history_available_from: '2026-01-02'
                      pending_supported: true
                    history_coverage:
                      requested_from: '2025-11-21'
                      oldest_booking_date: '2026-01-02'
                      covered_ranges:
                        - from: '2026-01-02'
                          to: '2026-11-21'
                      missing_ranges:
                        - from: '2025-11-21'
                          to: '2026-01-01'
                      status: partial
                      extended_auth_used: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BankDataAccessDenied'
        '404':
          description: La risorsa non esiste in questa applicazione e in questo ambiente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Not found:
                  summary: Non trovato
                  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
        '409':
          description: >-
            La persona non condivide più questo conto (`access_removed`), oppure
            la connessione è stata eliminata o i suoi dati non sono più
            leggibili (`connection_not_active`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Access removed:
                  summary: Accesso rimosso
                  value:
                    code: access_removed
                    message: The person no longer shares this account.
                    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/accounts/a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10/'
            \
              -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_account(
                "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.getAccount("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.GetAccount(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().getAccount("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->getAccount('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_account("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.GetAccountAsync("11111111-2222-3333-4444-555555555555");

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    BankAccount:
      type: object
      description: Un conto all'interno di una connessione.
      properties:
        id:
          type: string
          description: >-
            ID dell'account. Appartiene alla connessione e non cambia mai finché
            esiste, rinnovi inclusi.
          format: uuid
        connection_id:
          type: string
          format: uuid
        name:
          type: string
          nullable: true
        product:
          type: string
          description: Il nome del prodotto della banca.
          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: Codice valuta ISO 4217.
        holder_name:
          type: string
          description: Nome del titolare, dove la banca lo condivide.
          nullable: true
        holders:
          type: array
          items:
            $ref: '#/components/schemas/BankAccountHolder'
          description: >-
            Titolari condivisi dalla banca. Nell'assetto proprietario contano
            solo `holder` e `joint_holder`.
        identifiers:
          $ref: '#/components/schemas/BankAccountIdentifiers'
        account_ref:
          type: string
          description: >-
            Identifica lo stesso conto bancario tra le connessioni di una stessa
            applicazione e ambiente: un hash con chiave degli identificativi
            propri della banca. `null` quando la banca non fornisce un
            identificativo affidabile. Usalo per riconoscere un conto bancario
            già noto.
          nullable: true
        account_ref_previous:
          type: string
          description: >-
            Il precedente `account_ref`, solo per un alias verificato, come una
            migrazione bancaria.
          nullable: true
        status:
          type: string
          enum:
            - open
            - closed
            - access_removed
          description: >-
            `access_removed`: la persona ha rimosso il conto dal consenso. Non
            viene più sincronizzato.
        scopes_granted:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
        sync:
          $ref: '#/components/schemas/BankAccountSync'
        history_coverage:
          $ref: '#/components/schemas/BankHistoryCoverage'
      required:
        - id
        - connection_id
        - name
        - product
        - type
        - usage
        - currency
        - holder_name
        - holders
        - identifiers
        - account_ref
        - account_ref_previous
        - status
        - scopes_granted
        - sync
        - history_coverage
    BankDataError:
      type: object
      description: >-
        Corpo dell'errore di ogni operazione Bank data. Ogni campo è sempre
        presente.
      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: >-
            Codice di errore leggibile dalla macchina. Usalo per la diramazione
            della logica, mai `message`.
        message:
          type: string
          description: >-
            Spiegazione in linguaggio semplice per uno sviluppatore. Il testo
            può cambiare; non analizzarlo.
        request_id:
          type: string
          description: >-
            Identificativo di questa richiesta. Citalo quando contatti il
            supporto.
        field:
          type: string
          description: >-
            Il campo della richiesta da correggere, quando l'errore riguarda un
            solo campo. Altrimenti `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: >-
            Cosa fare dopo, così un client può agire senza fare supposizioni.
            `null` quando non esiste un passaggio successivo standard.
          nullable: true
        retry_after:
          type: integer
          description: >-
            Secondi da attendere prima di riprovare. Impostato in caso di limite
            di frequenza ed errori temporanei, altrimenti `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
    BankAccountHolder:
      type: object
      properties:
        name:
          type: string
        role:
          type: string
          enum:
            - holder
            - joint_holder
            - representative
            - unknown
      required:
        - name
        - role
    BankAccountIdentifiers:
      type: object
      description: >-
        Identificativi completi, restituiti ai chiamanti lato server con
        l'autorizzazione ai dati bancari.
      properties:
        iban:
          type: string
          description: IBAN completo, in maiuscolo e senza spazi.
          nullable: true
        bic:
          type: string
          nullable: true
        account_number:
          type: string
          description: Numero di conto locale, se il conto non ha un IBAN.
          nullable: true
        sort_code:
          type: string
          description: Codice banca locale, se il conto non ha un IBAN.
          nullable: true
        other:
          type: array
          items:
            type: object
            properties:
              scheme:
                type: string
              value:
                type: string
            required:
              - scheme
              - value
          description: Qualsiasi altro identificativo fornito dalla banca.
      required:
        - iban
        - bic
        - account_number
        - sort_code
        - other
    BankAccountSync:
      type: object
      properties:
        last_synced_at:
          type: string
          description: >-
            Quando i dati del conto sono stati recuperati l'ultima volta dalla
            banca.
          format: date-time
          nullable: true
        status:
          type: string
          enum:
            - pending
            - ok
            - failed
        history_requested_from:
          type: string
          format: date
          nullable: true
        history_available_from:
          type: string
          description: >-
            La data di contabilizzazione più vecchia che la banca ha
            effettivamente fornito per questo conto.
          format: date
          nullable: true
        pending_supported:
          type: boolean
          description: Se questa banca segnala le transazioni in attesa.
      required:
        - last_synced_at
        - status
        - history_requested_from
        - history_available_from
        - pending_supported
    BankHistoryCoverage:
      type: object
      description: Ciò che la banca ha restituito della cronologia richiesta.
      properties:
        requested_from:
          type: string
          description: La data di inizio richiesta.
          format: date
          nullable: true
        oldest_booking_date:
          type: string
          description: >-
            La data di contabilizzazione più vecchia effettivamente fornita
            dalla banca.
          format: date
          nullable: true
        covered_ranges:
          type: array
          items:
            $ref: '#/components/schemas/BankDateRange'
        missing_ranges:
          type: array
          items:
            $ref: '#/components/schemas/BankDateRange'
        status:
          type: string
          enum:
            - complete
            - partial
            - empty
            - unavailable
            - unknown
          description: >-
            `partial`: la banca ha fornito meno di quanto richiesto. `empty`: la
            banca ha confermato l'intera finestra e non contiene transazioni.
            `unavailable`: la banca non ha fornito lo storico. `unknown`: non
            ancora noto.
        extended_auth_used:
          type: boolean
          description: >-
            `true` quando la persona ha dato la conferma aggiuntiva che alcune
            banche richiedono prima di rilasciare la cronologia più datata.
      required:
        - requested_from
        - oldest_booking_date
        - covered_ranges
        - missing_ranges
        - status
        - extended_auth_used
    RateLimitBudgetError:
      type: object
      description: >-
        Restituito solo per un rifiuto del budget del middleware del limite di
        frequenza. Altri errori 429, inclusi i conflitti di idempotenza e i
        limiti specifici dell'endpoint, non garantiscono questi campi di
        metadati.
      required:
        - detail
        - reference
        - limit
        - remaining
        - reset
        - window_seconds
      properties:
        detail:
          type: string
          description: Messaggio di rifiuto per budget leggibile, già esistente.
        reference:
          type: string
          pattern: ^RL-[0-9a-f]{32}$
          description: >-
            Riferimento di supporto opaco: RL- seguito da 32 caratteri
            esadecimali minuscoli di un UUID.
        limit:
          type: integer
          description: Budget per l'ambito superato; equivale a X-RateLimit-Limit.
        remaining:
          type: integer
          minimum: 0
          description: Budget residuo, limitato a zero; equivale a X-RateLimit-Remaining.
        reset:
          type: integer
          format: int64
          description: >-
            Orario di reset della finestra in secondi Unix; coincide con
            X-RateLimit-Reset.
        window_seconds:
          type: integer
          description: >-
            Durata della finestra fissa in secondi, non il tempo di attesa
            residuo. Rispetta Retry-After prima di riprovare.
      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
    BankDateRange:
      type: object
      properties:
        from:
          type: string
          format: date
        to:
          type: string
          format: date
      required:
        - from
        - to
  responses:
    Unauthorized:
      description: Non autorizzato
      content:
        application/json:
          examples:
            Invalid API Key:
              summary: Chiave API non valida
              value:
                detail: Invalid API Key.
    BankDataAccessDenied:
      description: >-
        La chiave API non ha l'autorizzazione Bank data (`bank-data`) oppure,
        per i dati bancari grezzi in un'applicazione live, l'impostazione
        dell'applicazione "Bank data in the API" è disattivata. I dati bancari
        non fanno parte dell'accesso completo: una chiave con accesso completo,
        una chiave limitata ad altre risorse e una richiesta autenticata senza
        chiave API (client credentials, sui dati grezzi) vengono tutte rifiutate
        con questo messaggio, quindi crea una chiave e concedi l'autorizzazione
        in modo esplicito. Il rifiuto avviene prima di qualsiasi ricerca, quindi
        non dice nulla sull'esistenza di un oggetto.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Bank data not allowed:
              summary: Accesso ai dati bancari non consentito
              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: >-
        Budget di lettura del middleware superato. Rispetta Retry-After prima di
        riprovare.
      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: >-
        Si è verificato un problema lato Didit. Qualsiasi errore imprevisto
        sotto `/v3/bank/` risponde nel formato di errore Bank, mai con una
        pagina HTML: indica `request_id` al supporto.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Internal error:
              summary: Un errore imprevisto
              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: >-
        Secondi di attesa, arrotondati alla finestra successiva. Presente nei
        rifiuti per budget del middleware.
      schema:
        type: integer
    BudgetXRateLimitScope:
      description: >-
        L'ambito il cui budget è stato superato. Presente nei rifiuti per budget
        del middleware.
      schema:
        type: string
    BudgetXRateLimitLimit:
      description: >-
        Budget per l'ambito superato; equivale al limite nel corpo. Presente nei
        rifiuti per budget del middleware.
      schema:
        type: integer
    BudgetXRateLimitRemaining:
      description: >-
        Budget residuo, limitato a zero; equivale a remaining nel corpo.
        Presente nei rifiuti per budget del middleware.
      schema:
        type: integer
    BudgetXRateLimitReset:
      description: >-
        Orario di reset in secondi Unix; coincide con il reset nel corpo.
        Presente nei rifiuti per budget del middleware.
      schema:
        type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        La chiave API della tua applicazione, da Developers -> API keys nella
        Business Console. La chiave primaria ha accesso completo. Una chiave con
        nome può avere ambiti limitati: nessuno, lettura o scrittura per
        risorsa, limitata ad alcuni workflow o solo alle sessioni approvate, a
        un elenco di indirizzi IP e a una data di scadenza. 401 significa che la
        chiave è errata, revocata o scaduta; 403 significa che non è stata
        inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o
        azione, oppure che la richiesta proviene da un indirizzo esterno alla
        sua lista IP; 404 su una route di sessione significa che la sessione è
        al di fuori dei workflow o degli stati consentiti alla chiave. Una
        chiave senza accesso ai media riceve gli URL di immagini, video e PDF
        come null, e una chiave senza permesso di scrittura sulle sessioni
        riceve i link e i token delle sessioni come null. Vedi
        https://docs.didit.me/console/api-keys.

````

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