> ## 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 Account API: Identifiers, Holders and Sync

> Didit's Get an Account endpoint returns one account with its identifiers, holders, sync freshness and history coverage.

Didit's Get an Account endpoint returns one account with its identifiers, holders, sync freshness and history coverage.
`sync.last_synced_at` is when Didit last fetched from the bank.
Full identifiers need the bank data permission on your key.
See [Accounts, balances and transactions](https://docs.didit.me/core-technology/bank-verification/accounts-balances-transactions.md).


## OpenAPI

````yaml openapi-25.json GET /v3/bank/accounts/{account_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/accounts/{account_id}/:
    get:
      tags:
        - Bank Data
      summary: Get an account
      description: >-
        Returns one account with full identifiers, holders, sync state and
        `history_coverage`, which says what the bank delivered of the history
        you asked for. `sync.last_synced_at` is when the data was fetched from
        the bank, not when you read it.


        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`. A sandbox application reads its Test Bank data
        with the key alone. A request without an API key (client credentials) is
        refused on raw data with the same `403`.
      operationId: getBankAccount
      parameters:
        - name: account_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The account id.
      responses:
        '200':
          description: The account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
              examples:
                Business account:
                  summary: A business current account in Spain
                  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: 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
        '409':
          description: >-
            The person no longer shares this account (`access_removed`), or the
            connection was deleted or its data is no longer readable
            (`connection_not_active`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Access removed:
                  summary: Access removed
                  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: One account inside a connection.
      properties:
        id:
          type: string
          description: >-
            Account id. Belongs to the connection and never changes while it
            exists, renewals included.
          format: uuid
        connection_id:
          type: string
          format: uuid
        name:
          type: string
          nullable: true
        product:
          type: string
          description: The bank's product name.
          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.
        holder_name:
          type: string
          description: Holder name where the bank shares it.
          nullable: true
        holders:
          type: array
          items:
            $ref: '#/components/schemas/BankAccountHolder'
          description: >-
            Holders the bank shares. Ownership counts only `holder` and
            `joint_holder`.
        identifiers:
          $ref: '#/components/schemas/BankAccountIdentifiers'
        account_ref:
          type: string
          description: >-
            Identifies the same bank account across connections of one
            application and environment: a keyed hash of the bank's own
            identifiers. `null` when the bank gives no reliable identifier. Use
            it to recognise a bank account you already know.
          nullable: true
        account_ref_previous:
          type: string
          description: >-
            The previous `account_ref`, only for a verified alias such as a bank
            migration.
          nullable: true
        status:
          type: string
          enum:
            - open
            - closed
            - access_removed
          description: >-
            `access_removed`: the person removed the account from the consent.
            It is no longer synced.
        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: 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
    BankAccountHolder:
      type: object
      properties:
        name:
          type: string
        role:
          type: string
          enum:
            - holder
            - joint_holder
            - representative
            - unknown
      required:
        - name
        - role
    BankAccountIdentifiers:
      type: object
      description: >-
        Full identifiers, returned to server-side callers with the bank data
        permission.
      properties:
        iban:
          type: string
          description: Full IBAN, upper case without spaces.
          nullable: true
        bic:
          type: string
          nullable: true
        account_number:
          type: string
          description: Local account number, where the account has no IBAN.
          nullable: true
        sort_code:
          type: string
          description: Local bank code, where the account has no IBAN.
          nullable: true
        other:
          type: array
          items:
            type: object
            properties:
              scheme:
                type: string
              value:
                type: string
            required:
              - scheme
              - value
          description: Any other identifier the bank gives.
      required:
        - iban
        - bic
        - account_number
        - sort_code
        - other
    BankAccountSync:
      type: object
      properties:
        last_synced_at:
          type: string
          description: When the account's data was last fetched from the bank.
          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: The oldest booking date the bank really delivered for this account.
          format: date
          nullable: true
        pending_supported:
          type: boolean
          description: Whether this bank reports pending transactions.
      required:
        - last_synced_at
        - status
        - history_requested_from
        - history_available_from
        - pending_supported
    BankHistoryCoverage:
      type: object
      description: What the bank delivered of the history you asked for.
      properties:
        requested_from:
          type: string
          description: The start date that was asked for.
          format: date
          nullable: true
        oldest_booking_date:
          type: string
          description: The oldest booking date the bank really delivered.
          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`: the bank delivered less than asked. `empty`: the bank
            confirmed the whole window and it has no transactions.
            `unavailable`: the bank gave no history. `unknown`: not known yet.
        extended_auth_used:
          type: boolean
          description: >-
            `true` when the person gave the extra confirmation some banks ask
            for before releasing older history.
      required:
        - requested_from
        - oldest_booking_date
        - covered_ranges
        - missing_ranges
        - status
        - extended_auth_used
    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
    BankDateRange:
      type: object
      properties:
        from:
          type: string
          format: date
        to:
          type: string
          format: date
      required:
        - from
        - to
  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.