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

# List Bank Account Connections

> 
        Retrieve a paginated list of bank account connections with advanced filtering options and statistics.

        **Default Behavior:**
        - Returns all bank account connections for the authenticated partner's businesses
        - Uses summary serializer for list view (lighter payload)
        - Includes statistics for the filtered results

        **Statistics Included:**
        - Total account counts (total, active, inactive)
        - Sync status counts (synced, never synced)
        - Mapping status counts (mapped, unmapped)
        - Provider breakdown
        - Currency breakdown
        - Balance summary (total, average, min, max, account counts)

        **Filtering Options:**

        **Status Filters:**
        - `is_active`: Filter by active status (true/false)

        **Provider & Business Filters:**
        - `provider`: Filter by provider (e.g., 'plaid')
        - `bank_link_status`: Filter by bank link status
        - `business_id`: Filter by specific business UUID
        - `business_name`: Search business names

        **Account Filters:**
        - `currency`: Filter by currency code (USD, EUR, etc.)
        - `balance_min`: Minimum balance filter
        - `balance_max`: Maximum balance filter
        - `has_mapped_account`: Filter by whether account is mapped to chart of accounts
        - `mapped_account_id`: Filter by specific mapped account ID

        **Date Filters:**
        - `updated_after`: Accounts updated after date
        - `updated_before`: Accounts updated before date
        - `first_sync_after`: Accounts first synced after date
        - `first_sync_before`: Accounts first synced before date
        - `has_been_synced`: Filter by whether account has been synced

        **Search:**
        - `search`: Search across account names, keys, masks, and business names

        **Ordering:**
        - `ordering`: Order by any field (prefix with '-' for descending)
        - Default: `-created_at` (newest first)

        **Examples:**
        - Get all active accounts: `?is_active=true`
        - Get accounts for specific business: `?business_id=123e4567-e89b-12d3-a456-426614174000`
        - Get accounts that have been synced: `?has_been_synced=true`
        - Get mapped accounts: `?has_mapped_account=true`
        - Search for accounts: `?search=checking`
        - Order by balance: `?ordering=-balance`
        



## OpenAPI

````yaml GET /v1/platform/businesses/{business_id}/bank-accounts/
openapi: 3.0.3
info:
  title: Thredfi Accounting Platform API
  version: 1.0.0
  description: >-
    Comprehensive API for accounting, invoice management, open banking, and
    intelligence services.
servers: []
security: []
paths:
  /v1/platform/businesses/{business_id}/bank-accounts/:
    get:
      tags:
        - Bank Accounts Management
      summary: List Bank Account Connections
      description: |2-

                Retrieve a paginated list of bank account connections with advanced filtering options and statistics.

                **Default Behavior:**
                - Returns all bank account connections for the authenticated partner's businesses
                - Uses summary serializer for list view (lighter payload)
                - Includes statistics for the filtered results

                **Statistics Included:**
                - Total account counts (total, active, inactive)
                - Sync status counts (synced, never synced)
                - Mapping status counts (mapped, unmapped)
                - Provider breakdown
                - Currency breakdown
                - Balance summary (total, average, min, max, account counts)

                **Filtering Options:**

                **Status Filters:**
                - `is_active`: Filter by active status (true/false)

                **Provider & Business Filters:**
                - `provider`: Filter by provider (e.g., 'plaid')
                - `bank_link_status`: Filter by bank link status
                - `business_id`: Filter by specific business UUID
                - `business_name`: Search business names

                **Account Filters:**
                - `currency`: Filter by currency code (USD, EUR, etc.)
                - `balance_min`: Minimum balance filter
                - `balance_max`: Maximum balance filter
                - `has_mapped_account`: Filter by whether account is mapped to chart of accounts
                - `mapped_account_id`: Filter by specific mapped account ID

                **Date Filters:**
                - `updated_after`: Accounts updated after date
                - `updated_before`: Accounts updated before date
                - `first_sync_after`: Accounts first synced after date
                - `first_sync_before`: Accounts first synced before date
                - `has_been_synced`: Filter by whether account has been synced

                **Search:**
                - `search`: Search across account names, keys, masks, and business names

                **Ordering:**
                - `ordering`: Order by any field (prefix with '-' for descending)
                - Default: `-created_at` (newest first)

                **Examples:**
                - Get all active accounts: `?is_active=true`
                - Get accounts for specific business: `?business_id=123e4567-e89b-12d3-a456-426614174000`
                - Get accounts that have been synced: `?has_been_synced=true`
                - Get mapped accounts: `?has_mapped_account=true`
                - Search for accounts: `?search=checking`
                - Order by balance: `?ordering=-balance`
                
      operationId: list_bank_accounts
      parameters:
        - in: query
          name: account_key
          schema:
            type: string
          description: Filter by account key (partial match)
        - in: query
          name: balance_max
          schema:
            type: number
            format: double
          description: Filter by maximum balance
        - in: query
          name: balance_min
          schema:
            type: number
            format: double
          description: Filter by minimum balance
        - in: query
          name: bank_link_status
          schema:
            type: string
            enum:
              - active
              - error
              - revoked
          description: Filter by bank link status
        - in: path
          name: business_id
          schema:
            type: string
            format: uuid
          required: true
        - in: query
          name: business_id
          schema:
            type: string
          description: Filter by business ID (UUID format)
        - in: query
          name: business_name
          schema:
            type: string
          description: Filter by business name (partial match)
        - in: query
          name: currency
          schema:
            type: string
          description: Filter by currency code (USD, EUR, etc.)
        - in: query
          name: display_name
          schema:
            type: string
          description: Filter by display name (exact, case-insensitive)
        - in: query
          name: first_sync_after
          schema:
            type: string
            format: date-time
          description: Filter accounts first synced after this date
        - in: query
          name: first_sync_before
          schema:
            type: string
            format: date-time
          description: Filter accounts first synced before this date
        - in: query
          name: has_been_synced
          schema:
            type: boolean
          description: >-
            Filter by whether account has been synced (true for synced, false
            for never synced)
        - in: query
          name: has_mapped_account
          schema:
            type: boolean
          description: >-
            Filter by whether account is mapped (true for mapped, false for
            unmapped)
        - in: query
          name: is_active
          schema:
            type: boolean
          description: Filter by active status
        - in: query
          name: mapped_account
          schema:
            type: string
            format: uuid
        - in: query
          name: mapped_account_id
          schema:
            type: string
            format: uuid
          description: Filter by mapped account ID
        - in: query
          name: ordering
          schema:
            type: string
          description: Order by field (prefix with - for descending)
        - name: page
          required: false
          in: query
          description: A page number within the paginated result set.
          schema:
            type: integer
        - name: page_size
          required: false
          in: query
          description: Number of results to return per page.
          schema:
            type: integer
        - in: query
          name: provider
          schema:
            type: string
          description: Filter by provider (e.g., plaid)
        - in: query
          name: search
          schema:
            type: string
          description: Search in account names, keys, masks, and business names
        - in: query
          name: updated_after
          schema:
            type: string
            format: date-time
          description: Filter accounts updated after this date
        - in: query
          name: updated_before
          schema:
            type: string
            format: date-time
          description: Filter accounts updated before this date
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedBankAccountConnectionSummaryList'
              examples:
                UKBusinessBankAccountList(Summary):
                  value:
                    count: 123
                    page_info:
                      total_count: 123
                      current_page: 1
                      total_pages: 7
                      page_size: 20
                    results:
                      - id: 9f90c3cc-6i00-0h16-eeee-eii81402618g
                        display_name: Barclays Business Current Account
                        official_name: Barclays Bank PLC - Business Account
                        mask: '1234'
                        balance: 12500.5
                        balance_cents: 1250050
                        currency: GBP
                        is_active: true
                        bank_link_status: active
                        business_name: The Red Lion Pub Ltd
                        provider: plaid
                        created_at: '2024-01-15T10:30:00Z'
                  summary: UK Business Bank Account List (Summary)
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
          description: Validation errors in request data
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication required - missing or invalid API key
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Permission denied - insufficient privileges
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Conflict - resource already exists or invalid state transition
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable entity - business logic validation failed
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
        - BusinessScopedJWT: []
        - PartnerJWT: []
        - BasicAuth: []
        - BearerUnscoped: []
        - BearerBusinessScoped: []
components:
  schemas:
    PaginatedBankAccountConnectionSummaryList:
      type: object
      required:
        - count
        - page_info
        - results
      properties:
        count:
          type: integer
          example: 123
          description: Total number of items
        page_info:
          type: object
          example:
            total_count: 123
            current_page: 1
            total_pages: 7
            page_size: 20
          required:
            - total_count
            - current_page
            - total_pages
            - page_size
          properties:
            total_count:
              type: integer
              example: 123
              description: Total number of items (same as count)
            current_page:
              type: integer
              example: 1
              description: Current page number (1-indexed)
            total_pages:
              type: integer
              example: 7
              description: Total number of pages
            page_size:
              type: integer
              example: 20
              description: Number of items per page
        results:
          type: array
          items:
            $ref: '#/components/schemas/BankAccountConnectionSummary'
    ValidationErrorResponse:
      type: object
      description: Validation error response with field-specific errors
      properties:
        error_code:
          type: string
          description: Error code (e.g., 'validation_error')
        message:
          type: string
          nullable: true
          description: Human-readable error message
        detail:
          type: object
          additionalProperties: {}
          description: Contains field_errors and additional context
        request_id:
          type: string
          description: Request ID for tracing
      required:
        - detail
        - error_code
        - message
    ErrorResponse:
      type: object
      description: Standard error response format
      properties:
        error_code:
          type: string
          description: Error code for programmatic handling
        message:
          type: string
          nullable: true
          description: Human-readable error message
        detail:
          type: object
          additionalProperties: {}
          description: Additional error details including field_errors and debug info
        request_id:
          type: string
          description: Request ID for tracing
      required:
        - error_code
        - message
    BankAccountConnectionSummary:
      type: object
      description: |-
        Lightweight serializer for bank account connection summaries.

        Used for list views where detailed information is not needed.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique bank account connection identifier
        display_name:
          type: string
          description: User-friendly account name (e.g., 'Business Current Account')
          maxLength: 255
        official_name:
          type: string
          description: Official bank account name from the financial institution
          maxLength: 255
        mask:
          type: string
          description: Last 4 digits of account number for identification (e.g., '1234')
          maxLength: 10
        balance:
          type: number
          format: double
          nullable: true
          readOnly: true
          description: >-
            Current account balance in decimal format (e.g., 12500.50 for
            £12,500.50) - for backward compatibility
        balance_cents:
          type: integer
          readOnly: true
          description: Current account balance in cents (e.g., 1250050 for £12,500.50)
        currency:
          type: string
          description: Account currency code (GBP, EUR, USD)
          maxLength: 3
        is_active:
          type: boolean
          description: >-
            Whether this account connection is active and syncing transactions
            (false if disconnected)
        bank_link_status:
          type: string
          readOnly: true
          description: Bank link connection status (active, revoked, error)
        business_name:
          type: string
          readOnly: true
          description: Business name for display purposes
        provider:
          type: string
          readOnly: true
          description: Banking data provider (e.g., plaid, open_banking)
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when bank account was first connected
      required:
        - balance
        - balance_cents
        - bank_link_status
        - business_name
        - created_at
        - id
        - provider
  securitySchemes:
    BusinessScopedJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Business-scoped JWT token. Token payload includes `business_id` to
        automatically scope requests. Format: `Bearer <your-jwt-token>`


        **Use this for**: Business-specific operations where the business
        context is embedded in the token.
    PartnerJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Partner-level JWT token (unscoped). Token payload includes `partner_id`.
        Business access is validated via partner ownership. Format: `Bearer
        <your-jwt-token>`


        **Use this for**: Multi-business operations where the business_id is
        specified in the URL and partner has access to multiple businesses.
    BasicAuth:
      type: http
      scheme: basic
      description: >-
        Basic authentication for OAuth2 token endpoint. Use partner_uuid:api_key
        as username:password. Example: Authorization: Basic
        base64(partner_uuid:api_key)
    BearerUnscoped:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Partner (unscoped) JWT Bearer token. Obtain via POST
        /v1/platform/oauth2/token with Basic auth (partner_uuid:api_key). Use
        header: Authorization: Bearer {access_token}
    BearerBusinessScoped:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Business-scoped JWT Bearer token. Obtain via POST
        /v1/platform/{business_id}/oauth2/token/ using a partner Bearer token.
        Only valid for endpoints whose URL contains that business_id.

````