> ## 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 Transactions (Business-scoped) > Retrieve a paginated list of bank transactions for a specific business with advanced filtering options. Authentication: - Requires business-scoped Bearer token (ScopedBusinessTokenAuthentication) - Token business_id must match the business_id in the path **Default Behavior:** - Returns bank transactions for the business in the URL path - Uses summary serializer for list view (lighter payload) **Filtering Options:** **Account Filters:** - `account_id`: Filter by mapped account ID - `bank_account_connection_id`: Filter by bank account connection **Date Filters:** - `date_from`: Transactions from this date (ISO 8601 format) - `date_to`: Transactions to this date (ISO 8601 format) **Transaction Filters:** - `direction`: Filter by direction (credit/debit) - `categorization_status`: Filter by categorization status (supports multiple values) - `transaction_type`: Filter by transaction type (one of: fps, bacs, chaps, direct_debit, standing_order, sepa_credit, sepa_debit, sepa_instant, card_payment, atm_withdrawal, bank_transfer, fee, interest, other) - `source`: Filter by transaction source - `currency`: Filter by currency (GBP, EUR, USD) **Amount Filters:** - `amount_min`: Minimum transaction amount in cents - `amount_max`: Maximum transaction amount in cents **Status Filters:** - `is_reconciled`: Filter by reconciliation status - `needs_categorization`: Filter transactions needing categorization - `is_categorized`: Filter categorized transactions - `has_parent`: Filter split transactions - `has_children`: Filter transactions with splits **Search:** - `search`: Search across description, counterparty, merchant, and reference **Ordering:** - `ordering`: Order by any field (prefix with '-' for descending) - Default: `-date, -created_at` (newest first) **Examples:** - Get credit transactions: `?direction=credit` - Get pending categorization: `?categorization_status=pending` - Get multiple statuses: `?categorization_status=pending&categorization_status=manual_review` - Get transactions for date range: `?date_from=2025-01-01&date_to=2025-01-31` - Search transactions: `?search=amazon` - Filter by amount: `?amount_min=10000&amount_max=100000` (amounts in cents) ## OpenAPI ````yaml GET /v1/platform/businesses/{business_id}/bank-transactions/ 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-transactions/: get: tags: - Bank Transactions Management summary: List Bank Transactions (Business-scoped) description: |2- Retrieve a paginated list of bank transactions for a specific business with advanced filtering options. Authentication: - Requires business-scoped Bearer token (ScopedBusinessTokenAuthentication) - Token business_id must match the business_id in the path **Default Behavior:** - Returns bank transactions for the business in the URL path - Uses summary serializer for list view (lighter payload) **Filtering Options:** **Account Filters:** - `account_id`: Filter by mapped account ID - `bank_account_connection_id`: Filter by bank account connection **Date Filters:** - `date_from`: Transactions from this date (ISO 8601 format) - `date_to`: Transactions to this date (ISO 8601 format) **Transaction Filters:** - `direction`: Filter by direction (credit/debit) - `categorization_status`: Filter by categorization status (supports multiple values) - `transaction_type`: Filter by transaction type (one of: fps, bacs, chaps, direct_debit, standing_order, sepa_credit, sepa_debit, sepa_instant, card_payment, atm_withdrawal, bank_transfer, fee, interest, other) - `source`: Filter by transaction source - `currency`: Filter by currency (GBP, EUR, USD) **Amount Filters:** - `amount_min`: Minimum transaction amount in cents - `amount_max`: Maximum transaction amount in cents **Status Filters:** - `is_reconciled`: Filter by reconciliation status - `needs_categorization`: Filter transactions needing categorization - `is_categorized`: Filter categorized transactions - `has_parent`: Filter split transactions - `has_children`: Filter transactions with splits **Search:** - `search`: Search across description, counterparty, merchant, and reference **Ordering:** - `ordering`: Order by any field (prefix with '-' for descending) - Default: `-date, -created_at` (newest first) **Examples:** - Get credit transactions: `?direction=credit` - Get pending categorization: `?categorization_status=pending` - Get multiple statuses: `?categorization_status=pending&categorization_status=manual_review` - Get transactions for date range: `?date_from=2025-01-01&date_to=2025-01-31` - Search transactions: `?search=amazon` - Filter by amount: `?amount_min=10000&amount_max=100000` (amounts in cents) operationId: list_bank_transactions parameters: - in: query name: account_id schema: type: string description: Filter by mapped account ID (UUID format) - in: query name: amount_max schema: type: integer description: Filter by maximum amount in cents - in: query name: amount_min schema: type: integer description: Filter by minimum amount in cents - in: query name: approval_status schema: type: array items: type: string x-spec-enum-id: 7b698985e3218bf3 enum: - ai_approved - approved - pending_approval description: >- Filter by approval status (supports multiple values: ?approval_status=pending_approval&approval_status=ai_approved) * `pending_approval` - Pending Approval * `ai_approved` - AI Approved * `approved` - Approved explode: true style: form - in: query name: bank_account_connection_id schema: type: string description: Filter by bank account connection ID (UUID format) - in: query name: business_id schema: type: string format: uuid description: Filter by business ID - in: path name: business_id schema: type: string description: Business ID (UUID format) in path required: true - in: query name: categorization_status schema: type: string enum: - approved - categorized - manual_review - pending description: Filter by categorization status (supports multiple values) explode: true style: form - in: query name: category_code schema: type: string description: Filter by category code - in: query name: category_id schema: type: string format: uuid description: Filter by category ID - in: query name: currency schema: type: string enum: - EUR - GBP - USD description: Filter by currency - in: query name: date_from schema: type: string description: Filter transactions from this date (ISO 8601 format) - in: query name: date_to schema: type: string description: Filter transactions to this date (ISO 8601 format) - in: query name: direction schema: type: string enum: - credit - debit description: Filter by transaction direction - in: query name: has_children schema: type: boolean description: Filter transactions that have child splits - in: query name: has_parent schema: type: boolean description: Filter transactions that are split from parent - in: query name: is_categorized schema: type: boolean description: Filter transactions that are categorized - in: query name: is_reconciled schema: type: boolean description: Filter by reconciliation status - in: query name: needs_categorization schema: type: boolean description: Filter transactions that need categorization - 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: search schema: type: string description: Search in description, counterparty, merchant, and reference - in: query name: source schema: type: string enum: - api - csv_import - manual - open_banking - plaid description: Filter by transaction source - in: query name: subcategory_code schema: type: string description: Filter by subcategory code - in: query name: subcategory_id schema: type: string format: uuid description: Filter by subcategory ID - in: query name: transaction_type schema: type: string enum: - atm_withdrawal - bacs - bank_transfer - card_payment - chaps - direct_debit - fee - fps - interest - other - sepa_credit - sepa_debit - sepa_instant - standing_order description: Filter by transaction type responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedBankTransactionList' examples: UKBankTransaction(Credit-CustomerPayment): value: count: 123 page_info: total_count: 123 current_page: 1 total_pages: 7 page_size: 20 results: - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 date: '2024-03-28' amount: 450000 display_amount: £4,500.00 signed_amount: 450000 direction: credit currency: GBP counterparty_name: The Red Lion Pub Ltd merchant_name: The Red Lion Pub Ltd description: Payment for Invoice INV-0042 categorization_status: categorized transaction_type: fps subcategory: id: cat-001 code: INCOME_SALES name: Sales Revenue category: id: parent-001 code: INCOME name: Income business_id: 7d70c3cc-4g88-8f04-cccc-cgg69180406e business_name: Premium Breweries Ltd account_id: acc-1000 account_code: '1000' account_name: Bank - Barclays Current bank_account_connection_id: 9f90c3cc-6i00-0h16-eeee-eii81402618g bank_account_name: Barclays Business Current Account bank_account_mask: '1234' bank_account_currency: GBP is_reconciled: true reconciled_at: '2024-03-28T10:15:00Z' reconciled_amount_cents: 450000 remaining_amount_cents: 0 reconciliations: null created_at: '2024-03-28T10:05:00Z' summary: UK Bank Transaction (Credit - Customer Payment) 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: [] - BasicAuth: [] - BearerUnscoped: [] - BearerBusinessScoped: [] components: schemas: PaginatedBankTransactionList: 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/BankTransaction' 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 BankTransaction: type: object description: |- Serializer for bank transaction list views. Contains essential fields for list display with better performance. properties: id: type: string format: uuid readOnly: true description: Unique bank transaction identifier date: type: string format: date-time description: Transaction date (YYYY-MM-DD format) amount: type: integer description: Transaction amount in cents (unsigned, e.g., 450000 for £4,500.00) readOnly: true display_amount: type: string readOnly: true description: Formatted transaction amount for display (e.g., '£4,500.00') signed_amount: type: integer description: >- Signed transaction amount in cents (positive for credit/incoming, negative for debit/outgoing) readOnly: true direction: enum: - credit - debit type: string x-spec-enum-id: df4966e234dbb91d description: >- Transaction direction: 'credit' (money in/incoming) or 'debit' (money out/outgoing) * `credit` - Credit (Money In) * `debit` - Debit (Money Out) currency: enum: - EUR - GBP - USD - SEK - NOK - DKK - ISK - MYR - SGD type: string x-spec-enum-id: 7e6a70e4775b3009 description: |- Transaction currency code (GBP, EUR, USD) * `EUR` - Euro * `GBP` - British Pound * `USD` - US Dollar * `SEK` - Swedish Krona * `NOK` - Norwegian Krone * `DKK` - Danish Krone * `ISK` - Icelandic Króna * `MYR` - Malaysian Ringgit * `SGD` - Singapore Dollar counterparty_name: type: string description: >- Name of the other party in the transaction (customer/vendor name, null if not available) maxLength: 255 merchant_name: type: string description: >- Merchant or business name (from card payment data, null if not available) maxLength: 255 description: type: string description: >- Transaction description from bank feed (e.g., 'Payment for Invoice INV-0042') maxLength: 500 categorization_status: enum: - pending - categorized - manual_review - approved type: string x-spec-enum-id: af30d82e198cc7fb description: >- Categorization workflow status: pending, categorized, manual_review, approved * `pending` - Pending Review * `categorized` - AI Categorized * `manual_review` - Requires Manual Review * `approved` - Approved approval_status: enum: - pending_approval - ai_approved - approved type: string x-spec-enum-id: 7b698985e3218bf3 description: >- Approval status for posting: pending_approval (needs review), ai_approved (auto-approved by AI), approved (human approved). JE triggers when approved. * `pending_approval` - Pending Approval * `ai_approved` - AI Approved * `approved` - Approved transaction_type: enum: - fps - bacs - chaps - direct_debit - standing_order - sepa_credit - sepa_debit - sepa_instant - card_payment - atm_withdrawal - bank_transfer - fee - interest - other - '' type: string x-spec-enum-id: 5d65d8aa555eb7d4 description: >- UK/EU bank transaction type: fps (Faster Payments), bacs, chaps, direct_debit, standing_order, sepa_credit, sepa_debit, sepa_instant, card_payment, atm_withdrawal, bank_transfer, fee, interest, other * `fps` - Faster Payment * `bacs` - BACS Payment * `chaps` - CHAPS Payment * `direct_debit` - Direct Debit * `standing_order` - Standing Order * `sepa_credit` - SEPA Credit Transfer * `sepa_debit` - SEPA Direct Debit * `sepa_instant` - SEPA Instant Payment * `card_payment` - Card Payment * `atm_withdrawal` - ATM Withdrawal * `bank_transfer` - Bank Transfer * `fee` - Bank Fee * `interest` - Interest * `other` - Other subcategory: allOf: - $ref: '#/components/schemas/SubcategoryWithCategory' readOnly: true nullable: true description: >- Transaction subcategory with nested category details (null if not categorized) business_id: type: string format: uuid readOnly: true nullable: true description: Business UUID that owns this transaction business_name: type: string readOnly: true nullable: true description: Business name for display purposes account_id: type: string format: uuid readOnly: true nullable: true description: >- Chart of accounts ID this transaction is categorized to (null if not categorized) account_code: type: string readOnly: true nullable: true description: Account code from chart of accounts (e.g., '1000' for bank account) account_name: type: string readOnly: true nullable: true description: >- Account name from chart of accounts (e.g., 'Bank - Barclays Current') bank_account_connection_id: type: string format: uuid readOnly: true nullable: true description: Bank account connection UUID this transaction belongs to bank_account_name: type: string readOnly: true nullable: true description: >- Display name of the bank account (e.g., 'Barclays Business Current Account') bank_account_mask: type: string readOnly: true nullable: true description: Last 4 digits of the bank account number (e.g., '1234') bank_account_currency: type: string readOnly: true nullable: true description: Currency of the bank account (GBP, EUR, USD) is_reconciled: type: boolean readOnly: true description: >- Whether this transaction has been reconciled to invoices/bills/payments reconciled_at: type: string format: date-time readOnly: true nullable: true description: >- Timestamp when transaction was first reconciled (null if not reconciled) reconciled_amount_cents: type: integer readOnly: true description: >- Total amount reconciled in cents (sum of all confirmed reconciliation links) remaining_amount_cents: type: integer readOnly: true description: >- Remaining unreconciled amount in cents (amount - reconciled_amount_cents) reconciliations: type: array items: $ref: '#/components/schemas/BankTransactionReconciliationDetail' nullable: true readOnly: true description: >- List of reconciliation links showing what this transaction is matched to (invoices/bills/payments) - only populated in detail view created_at: type: string format: date-time readOnly: true description: Timestamp when transaction was imported into the system required: - account_code - account_id - account_name - amount - bank_account_connection_id - bank_account_currency - bank_account_mask - bank_account_name - business_id - business_name - created_at - date - direction - display_amount - id - is_reconciled - reconciled_amount_cents - reconciled_at - reconciliations - remaining_amount_cents - signed_amount - subcategory SubcategoryWithCategory: type: object description: |- Serializer for subcategory with parent category details. Used in transaction responses to show both category and subcategory. properties: id: type: string format: uuid readOnly: true code: type: string description: >- Code for the subcategory (e.g., 'local_transport', 'saas_subscriptions') maxLength: 100 name: type: string description: >- Display name for the subcategory (e.g., 'Local Transport', 'SaaS Subscriptions') maxLength: 200 description: type: string description: >- Detailed description of what types of transactions belong to this subcategory full_code: type: string readOnly: true category: allOf: - $ref: '#/components/schemas/TransactionCategory' readOnly: true is_active: type: boolean description: Whether this subcategory is active and available for selection required: - category - code - full_code - id - name BankTransactionReconciliationDetail: type: object description: Detailed reconciliation info for a bank transaction properties: reconciliation_link_id: type: string format: uuid entity_type: type: string description: >- Type: payment, bill_payment, receipt, refund_payment, vendor_refund_payment entity_id: type: string format: uuid amount_cents: type: integer status: type: string created_at: type: string format: date-time created_by: type: string notes: type: string required: - amount_cents - created_at - entity_id - entity_type - reconciliation_link_id - status TransactionCategory: type: object description: |- Serializer for transaction category without nested subcategories. Used when only category information is needed. properties: id: type: string format: uuid readOnly: true code: type: string description: >- Unique code for the category (e.g., 'travel_and_transport', 'software_and_it') maxLength: 100 name: type: string description: >- Display name for the category (e.g., 'Travel & Transport', 'Software & IT') maxLength: 200 description: type: string description: >- Detailed description of what types of transactions belong to this category is_active: type: boolean description: Whether this category is active and available for selection required: - code - id - name securitySchemes: BusinessScopedJWT: type: http scheme: bearer bearerFormat: JWT description: >- Business-scoped JWT token. Token payload includes `business_id` to automatically scope requests. Format: `Bearer ` **Use this for**: Business-specific operations where the business context is embedded in the token. 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. ````