> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quidkey.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Read a bank account

> Reads one live bank account. An account that serves only test payment transactions answers 404, and so does a `virtual` account at a provider the merchant isn't onboarded with. A caller without permission to read balances gets the account, with its balance in `not_included`.

Credentials: `partner`, `merchant`

Permission: `bank-accounts:get`



## OpenAPI

````yaml /api-reference/v1/openapi.json get /bank-accounts/{id}
openapi: 3.1.0
info:
  title: Quidkey API
  version: 1.0.0
  description: >-
    The Quidkey public API.


    Within a version, a response can carry what this document doesn't list yet:
    a new field, a new value of an enum, a new error code. Handle a value you
    don't recognise rather than refusing the response. A client generated from
    this document turns an `enum` into a closed type unless told otherwise, so
    turn on its option for unknown values, such as openapi-generator's
    `enumUnknownDefaultCase`. A request is held to what's listed: a value it
    doesn't list is refused.
  contact:
    name: Quidkey
    url: https://docs.quidkey.com
servers:
  - url: https://api.quidkey.com/v1
security:
  - bearer: []
tags:
  - name: account_owner
  - name: agreement
  - name: agreement_acceptance
  - name: api_key
  - name: bank
  - name: bank_account
  - name: capability
  - name: country
  - name: identity_verification
  - name: legal_entity
  - name: merchant
  - name: party
  - name: payment_link
  - name: payout
  - name: transaction
  - name: webhook_endpoint
paths:
  /bank-accounts/{id}:
    get:
      tags:
        - bank_account
      summary: Read a bank account
      description: >-
        Reads one live bank account. An account that serves only test payment
        transactions answers 404, and so does a `virtual` account at a provider
        the merchant isn't onboarded with. A caller without permission to read
        balances gets the account, with its balance in `not_included`.


        Credentials: `partner`, `merchant`


        Permission: `bank-accounts:get`
      operationId: bank_account.get
      parameters:
        - name: id
          in: path
          required: true
          schema:
            minLength: 1
            type: string
        - name: include
          in: query
          required: false
          description: >-
            Link fields to hydrate into `entities`, comma-separated. Sending it
            replaces the default, which is nothing.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - balance
        - name: view
          in: query
          required: false
          description: The representation to answer with.
          schema:
            type: string
            enum:
              - full
            default: full
      responses:
        '200':
          description: The bank_account, in the full view.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                additionalProperties: false
                type: object
                required:
                  - result
                  - entities
                  - not_included
                properties:
                  result:
                    $ref: '#/components/schemas/BankAccountFull'
                  entities:
                    additionalProperties:
                      $ref: '#/components/schemas/BalanceFull'
                    description: Included linked resources, keyed by URI.
                    type: object
                    properties: {}
                  not_included:
                    type: array
                    items:
                      $ref: '#/components/schemas/NotIncludedEntry'
        '400':
          description: '`VALIDATION_FAILED`: The request is malformed or failed validation.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - VALIDATION_FAILED
        '401':
          description: '`UNAUTHENTICATED`: A valid bearer token is required.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - UNAUTHENTICATED
        '403':
          description: >-
            `FORBIDDEN`: This credential doesn't have permission for this
            endpoint.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - FORBIDDEN
        '404':
          description: '`NOT_FOUND`: Not found.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - NOT_FOUND
        '406':
          description: '`NOT_ACCEPTABLE`: This endpoint doesn''t offer the format in Accept.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - NOT_ACCEPTABLE
        '429':
          description: '`RATE_LIMITED`: Too many requests.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - RATE_LIMITED
        '500':
          description: '`INTERNAL_ERROR`: Something went wrong on our side.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - INTERNAL_ERROR
        '503':
          description: '`SERVICE_UNAVAILABLE`: The service is busy. Try again shortly.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - SERVICE_UNAVAILABLE
components:
  headers:
    RequestId:
      description: Identifies this request. Quote it to support.
      schema:
        type: string
    RetryAfter:
      description: How many seconds to wait before retrying.
      schema:
        minimum: 0
        type: integer
  schemas:
    BankAccountFull:
      additionalProperties: false
      type: object
      required:
        - _type
        - _uri
        - _view
        - id
        - created_at
        - updated_at
        - merchant
        - status
        - account_type
        - account_roles
        - currency
        - country
        - account_holder_name
        - bic
        - sort_code
        - routing_number
        - bsb
        - ownership_status
        - ownership_verified_at
        - masked_identifier
        - payment_schemes
        - balance
      properties:
        _type:
          const: bank_account
          type: string
        _uri:
          pattern: ^/
          description: The canonical URI, relative to the version root.
          type: string
        _view:
          const: full
          type: string
        id:
          type: string
        created_at:
          anyOf:
            - format: date-time
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$
              type: string
            - type: 'null'
        updated_at:
          anyOf:
            - format: date-time
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$
              type: string
            - type: 'null'
        merchant:
          $ref: '#/components/schemas/MerchantLink'
        status:
          type: string
          enum:
            - active
            - inactive
          description: >-
            `active` can be used in its roles. That alone doesn't mean a payout
            will reach it: see `ownership_status`, and Quidkey registers a new
            `owned` account with the providers that pay it without waiting for
            them, so a payout to one that hasn't registered fails. `inactive` is
            final, and a new account is the way back.
        account_type:
          type: string
          enum:
            - owned
            - virtual
          description: >-
            `owned` is the merchant's own account elsewhere. `virtual` is held
            for the merchant by Quidkey.
        account_roles:
          type: array
          items:
            type: string
            enum:
              - payment
              - payout
              - refund
          description: >-
            What this account can be used for, which isn't that it's in use. For
            each currency Quidkey keeps at most one route for live payment
            transactions and one for payouts, each naming one account, and only
            that account is used. `payment`: a route can send payment
            transactions here. `payout`: a route can send payouts here, which
            only an `owned` account can have. `refund`: funds refunds, and holds
            what's retained from payouts for them. An account added by a bank
            link is `payout` only.
        currency:
          pattern: ^[A-Z]{3}$
          type: string
          description: >-
            A route sends this account money only in this currency. A payment
            transaction through a virtual account with no `payout` account in
            its own currency is converted, as the merchant's `home_currency`
            says.
        country:
          anyOf:
            - pattern: ^[A-Z]{2}$
              type: string
            - type: 'null'
          description: The account's country. `null` when none is held.
        account_holder_name:
          anyOf:
            - type: string
            - type: 'null'
        bic:
          anyOf:
            - type: string
            - type: 'null'
          description: Identifies a bank, not an account.
        sort_code:
          anyOf:
            - type: string
            - type: 'null'
        routing_number:
          anyOf:
            - type: string
            - type: 'null'
        bsb:
          anyOf:
            - type: string
            - type: 'null'
        ownership_status:
          type: string
          enum:
            - pending
            - verified
            - not_applicable
          description: >-
            `pending`: this `owned` account is `pending` until Quidkey verifies
            it's the merchant's. While Quidkey's verification hold is on, a
            payout to it waits and a live payment transaction into it is
            refused, with `LIVE_PAYMENTS_NOT_ALLOWED`. A merchant can go live
            with one, and uploads a statement for it in Quidkey's Console, as
            this API takes none. `verified`: Quidkey takes the account as the
            merchant's. `not_applicable`: a `virtual` account, which Quidkey
            opens itself.
        ownership_verified_at:
          anyOf:
            - format: date-time
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$
              type: string
            - type: 'null'
          description: When Quidkey took the account as verified. Set once.
        masked_identifier:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The end of the account's number behind `****`, or of its other
            identifier on an account with no number. With its spaces and
            punctuation gone, it shows at most the last 4 characters and at most
            half of it. It helps tell accounts apart, though two can share one.
            `null` where that leaves 4 characters or fewer, or where Quidkey
            holds none. The number itself is never returned.
        payment_schemes:
          maxItems: 20
          type: array
          items:
            additionalProperties: false
            type: object
            required:
              - _type
              - id
              - is_active
            properties:
              _type:
                const: payment_scheme
                type: string
              id:
                type: string
              is_active:
                type: boolean
            x-link-target:
              resource: payment_scheme
              kind: resource
              is_published: false
          description: >-
            `id` is the scheme's stable code, such as `faster_payments`.
            `is_active` says whether Quidkey offers this scheme for a payment
            transaction routed to this account. A false doesn't by itself refuse
            a payment transaction, and it says nothing while the account is
            `inactive`. It has no part in how a payout reaches the account.
            Empty where none is attached, as on an account added by a bank link.
        balance:
          anyOf:
            - $ref: '#/components/schemas/BalanceSubResourceLink'
            - type: 'null'
          description: Set on an active `virtual` account, and `null` otherwise.
    BalanceFull:
      additionalProperties: false
      type: object
      required:
        - _type
        - _uri
        - _view
        - id
        - created_at
        - updated_at
        - bank_account
        - amount
        - retrieved_at
      properties:
        _type:
          const: balance
          type: string
        _uri:
          pattern: ^/
          description: The canonical URI, relative to the version root.
          type: string
        _view:
          const: full
          type: string
        id:
          type: string
        created_at:
          anyOf:
            - format: date-time
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$
              type: string
            - type: 'null'
        updated_at:
          anyOf:
            - format: date-time
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$
              type: string
            - type: 'null'
        bank_account:
          $ref: '#/components/schemas/BankAccountLink'
        amount:
          anyOf:
            - type: object
              allOf:
                - $ref: '#/components/schemas/Money'
                - type: object
                  required:
                    - value
                  properties:
                    value:
                      minimum: -9007199254740991
                      maximum: 9007199254740991
                      type: integer
            - type: 'null'
          description: >-
            The balance the provider reports. `null` means Quidkey couldn't get
            a figure from the provider, and never zero.
        retrieved_at:
          anyOf:
            - format: date-time
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$
              type: string
            - type: 'null'
          description: >-
            When Quidkey had the provider's answer. `null` when `amount` is
            `null`.
    NotIncludedEntry:
      additionalProperties: false
      type: object
      required:
        - link
        - reason
      properties:
        link:
          $ref: '#/components/schemas/AnyLink'
        reason:
          type: string
          enum:
            - no_permission
            - not_published
          description: >-
            Why this link has no entity.


            - `no_permission`: This credential can't read it. Fetching it
            answers 403, or 404 where a 403 would reveal that it exists.

            - `not_published`: The API doesn't show it: a type it doesn't
            publish, or a record it doesn't show on a type it does, such as a
            failed payout. Fetching it, where it has a URI, answers 404.
    Error:
      additionalProperties: false
      type: object
      required:
        - error
      properties:
        error:
          additionalProperties: false
          type: object
          required:
            - code
            - message
            - details
            - retryable
            - request_id
          properties:
            code:
              description: Branch on this. New codes can appear.
              type: string
            message:
              description: For people. It can change.
              type: string
            details:
              type: array
              items:
                $ref: '#/components/schemas/ErrorDetail'
            retryable:
              description: >-
                Whether sending the same request again unchanged, after a wait,
                can succeed with nothing else changing.
              type: boolean
            request_id:
              description: Quote this to support.
              type: string
    MerchantLink:
      additionalProperties: false
      type: object
      required:
        - _link
        - _type
        - id
      properties:
        _link:
          pattern: ^/
          type: string
        _type:
          const: merchant
          type: string
        id:
          type: string
      x-link-target:
        resource: merchant
        kind: resource
        is_published: true
        views:
          - full
    BalanceSubResourceLink:
      additionalProperties: false
      type: object
      required:
        - _link
        - _type
        - id
      properties:
        _link:
          pattern: ^/
          type: string
        _type:
          const: balance
          type: string
        id:
          type: string
      x-link-target:
        resource: balance
        kind: singleton
        is_published: true
        views:
          - full
    BankAccountLink:
      additionalProperties: false
      type: object
      required:
        - _link
        - _type
        - id
      properties:
        _link:
          pattern: ^/
          type: string
        _type:
          const: bank_account
          type: string
        id:
          type: string
      x-link-target:
        resource: bank_account
        kind: resource
        is_published: true
        views:
          - full
    Money:
      description: An amount of money. Decimal values are refused, not rounded.
      additionalProperties: false
      type: object
      required:
        - value
        - currency
      properties:
        value:
          description: In the currency's ISO 4217 minor units, so GBP 45.00 is 4500.
          type: integer
        currency:
          pattern: ^[A-Z]{3}$
          type: string
    AnyLink:
      anyOf:
        - additionalProperties: false
          type: object
          required:
            - _link
            - _type
            - id
          properties:
            _link:
              pattern: ^/
              type: string
            _type:
              type: string
            id:
              type: string
        - additionalProperties: false
          type: object
          required:
            - _type
            - id
          properties:
            _type:
              type: string
            id:
              type: string
      x-link-target:
        resource: any
        kind: any
        is_published: true
    ErrorDetail:
      anyOf:
        - additionalProperties: false
          type: object
          required:
            - field
            - message
          properties:
            field:
              type: string
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - required_actions
            - message
          properties:
            required_actions:
              description: The `required_actions` codes holding this back.
              type: array
              items:
                type: string
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - available_percent
            - message
          properties:
            available_percent:
              $ref: '#/components/schemas/Percent'
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - agreement
            - message
          properties:
            agreement:
              $ref: '#/components/schemas/AgreementLink'
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - agreement
            - current_agreement
            - message
          properties:
            agreement:
              $ref: '#/components/schemas/AgreementLink'
            current_agreement:
              $ref: '#/components/schemas/AgreementLink'
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - legal_entity
            - message
          properties:
            legal_entity:
              $ref: '#/components/schemas/LegalEntityLink'
            message:
              type: string
    Percent:
      pattern: ^\d+(\.\d+)?$
      description: 'A percentage as a decimal string: `"25.00"` is 25%.'
      type: string
    AgreementLink:
      additionalProperties: false
      type: object
      required:
        - _link
        - _type
        - id
      properties:
        _link:
          pattern: ^/
          type: string
        _type:
          const: agreement
          type: string
        id:
          type: string
      x-link-target:
        resource: agreement
        kind: resource
        is_published: true
        views:
          - full
    LegalEntityLink:
      additionalProperties: false
      type: object
      required:
        - _link
        - _type
        - id
      properties:
        _link:
          pattern: ^/
          type: string
        _type:
          const: legal_entity
          type: string
        id:
          type: string
      x-link-target:
        resource: legal_entity
        kind: resource
        is_published: true
        views:
          - full
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````

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