> ## 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 chart of accounts

> 
        List all accounts with current balances for a business.

        **Features:**
        - Filter by account type (Assets, Liabilities, Equity, Revenue, Expenses)
        - Filter by fiscal year (accounts with activity in that year)
        - Filter by specific accounting period (year + month)
        - Filter by parent account (hierarchical view)
        - Search by account name or code
        - Include/exclude zero balance accounts
        - Group accounts by type (Assets, Liabilities, etc.)
        - Pagination support (default: 20 per page, max: 100)

        **Response includes:**
        - Account code, name, type, sub-type
        - Current balance (from ledger)
        - Formatted balance with currency symbol (€, £, $)
        - Period-specific balance (if period filters applied)
        - Debit and credit balances
        - Parent/child account relationships
        - Hierarchy level and children indicator

        **Grouping:**
        Use `group_by=type` to get accounts grouped by:
        - Assets (Current, Fixed, Other)
        - Liabilities (Current, Long-term)
        - Equity
        - Revenue
        - Expenses (Operating, COGS)

        **Period Filtering:**
        Use both `period_year` and `period_month` together to get period-specific balances.
        Example: `period_year=2024&period_month=11` for November 2024.

        **Account Types (5 fundamental types):**
        - `asset`: Asset (use account_subtype for current/fixed/other)
        - `liability`: Liability (use account_subtype for current/long_term)
        - `equity`: Equity
        - `revenue`: Revenue
        - `expense`: Expense (use account_subtype for operating/cogs)
        



## OpenAPI

````yaml GET /v1/platform/businesses/{business_id}/general-ledger/chart-of-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}/general-ledger/chart-of-accounts/:
    get:
      tags:
        - General Ledger
      summary: List chart of accounts
      description: |2-

                List all accounts with current balances for a business.

                **Features:**
                - Filter by account type (Assets, Liabilities, Equity, Revenue, Expenses)
                - Filter by fiscal year (accounts with activity in that year)
                - Filter by specific accounting period (year + month)
                - Filter by parent account (hierarchical view)
                - Search by account name or code
                - Include/exclude zero balance accounts
                - Group accounts by type (Assets, Liabilities, etc.)
                - Pagination support (default: 20 per page, max: 100)

                **Response includes:**
                - Account code, name, type, sub-type
                - Current balance (from ledger)
                - Formatted balance with currency symbol (€, £, $)
                - Period-specific balance (if period filters applied)
                - Debit and credit balances
                - Parent/child account relationships
                - Hierarchy level and children indicator

                **Grouping:**
                Use `group_by=type` to get accounts grouped by:
                - Assets (Current, Fixed, Other)
                - Liabilities (Current, Long-term)
                - Equity
                - Revenue
                - Expenses (Operating, COGS)

                **Period Filtering:**
                Use both `period_year` and `period_month` together to get period-specific balances.
                Example: `period_year=2024&period_month=11` for November 2024.

                **Account Types (5 fundamental types):**
                - `asset`: Asset (use account_subtype for current/fixed/other)
                - `liability`: Liability (use account_subtype for current/long_term)
                - `equity`: Equity
                - `revenue`: Revenue
                - `expense`: Expense (use account_subtype for operating/cogs)
                
      operationId: list_chart_of_accounts
      parameters:
        - in: query
          name: account_type
          schema:
            type: string
          description: >-
            Filter by account type (case-insensitive). Values: asset, liability,
            equity, revenue, expense
        - in: path
          name: business_id
          schema:
            type: string
            format: uuid
          description: Business UUID
          required: true
        - in: query
          name: fiscal_year
          schema:
            type: integer
          description: >-
            Filter to show only accounts with journal entry activity in the
            specified fiscal year. Note: For export endpoint, use fiscal_year to
            calculate period-specific balances instead.
        - in: query
          name: group_by
          schema:
            type: string
          description: >-
            Group accounts by category. Values: 'type' (groups by Assets,
            Liabilities, Equity, Revenue, Expenses)
        - in: query
          name: include_zero_balance
          schema:
            type: boolean
            default: true
          description: 'Include accounts with zero balance (default: true)'
        - in: query
          name: is_active
          schema:
            type: boolean
        - in: query
          name: page
          schema:
            type: integer
          description: 'Page number (default: 1). Not used when group_by is specified.'
        - in: query
          name: page_size
          schema:
            type: integer
          description: >-
            Items per page (default: 20, max: 100). Not used when group_by is
            specified.
        - in: query
          name: parent_account_id
          schema:
            type: string
            format: uuid
          description: Filter by parent account UUID (show sub-accounts only)
        - in: query
          name: period_month
          schema:
            type: integer
          description: >-
            Month for period-specific balance calculation (1-12). Must be used
            with period_year.
        - in: query
          name: period_year
          schema:
            type: integer
          description: >-
            Year for period-specific balance calculation (e.g., 2024). Must be
            used with period_month.
        - in: query
          name: search
          schema:
            type: string
          description: Search by account name, code, or institution name
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedChartOfAccountListList'
              examples:
                UKChartOfAccounts-BankAccount:
                  value:
                    count: 123
                    page_info:
                      total_count: 123
                      current_page: 1
                      total_pages: 7
                      page_size: 20
                    results:
                      - id: acc-1000-uuid
                        code: '1000'
                        name: Bank - Barclays Current
                        currency: GBP
                        account_type: asset
                        account_type_display: Asset
                        account_subtype: current_assets
                        account_subtype_display: Current Assets
                        parent_account_code: null
                        current_balance: 1250050
                        current_balance_formatted: £12,500.50
                        debit_balance: 1500000
                        credit_balance: 249950
                        period_balance: null
                        period_balance_formatted: null
                        has_children: false
                        hierarchy_level: 0
                        is_active: true
                  summary: UK Chart of Accounts - Bank Account
          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:
        - PartnerJWT: []
        - BusinessScopedJWT: []
        - BasicAuth: []
        - BearerUnscoped: []
        - BearerBusinessScoped: []
components:
  schemas:
    PaginatedChartOfAccountListList:
      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/ChartOfAccountList'
    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
    ChartOfAccountList:
      type: object
      description: Serializer for listing chart of accounts with balance information.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique account identifier
        code:
          type: string
          readOnly: true
          description: Account code from chart of accounts (e.g., '1000', '4000')
        name:
          type: string
          description: Account name from chart of accounts
          readOnly: true
        currency:
          type: string
          description: Account currency from business base currency (GBP, EUR, USD)
          readOnly: true
        account_type:
          enum:
            - asset
            - liability
            - equity
            - revenue
            - expense
          type: string
          x-spec-enum-id: bee27527493b2230
          readOnly: true
          description: |-
            Account type code (asset, liability, equity, revenue, expense)

            * `asset` - Asset
            * `liability` - Liability
            * `equity` - Equity
            * `revenue` - Revenue
            * `expense` - Expense
        account_type_display:
          type: string
          nullable: true
          description: Human-readable account type (e.g., 'Current Asset', 'Revenue')
          readOnly: true
        account_subtype:
          enum:
            - current_assets
            - non_current_assets
            - current_liabilities
            - non_current_liabilities
            - share_capital
            - share_premium
            - reserves
            - retained_earnings
            - revenue
            - other_operating_income
            - finance_income
            - direct_costs
            - operating_expenses
            - finance_costs
            - income_tax
          type: string
          x-spec-enum-id: f729e72199be4c29
          readOnly: true
          description: >-
            Account subtype code for more granular classification (bank, cash,
            etc.)


            * `current_assets` - Current Assets

            * `non_current_assets` - Non-current Assets

            * `current_liabilities` - Current Liabilities

            * `non_current_liabilities` - Non-current Liabilities

            * `share_capital` - Share Capital

            * `share_premium` - Share Premium

            * `reserves` - Reserves

            * `retained_earnings` - Retained Earnings

            * `revenue` - Revenue

            * `other_operating_income` - Other Operating Income

            * `finance_income` - Finance Income

            * `direct_costs` - Direct Costs

            * `operating_expenses` - Operating Expenses

            * `finance_costs` - Finance Costs

            * `income_tax` - Income Tax
        account_subtype_display:
          type: string
          nullable: true
          description: Account subtype for more granular classification
          readOnly: true
        parent_account_code:
          type: string
          nullable: true
          description: >-
            Parent account code if this is a sub-account (null for top-level
            accounts)
          readOnly: true
        current_balance:
          type: integer
          description: Current balance in cents
          readOnly: true
        current_balance_formatted:
          type: string
          description: Formatted balance with currency symbol (e.g., '£12,500.50')
          readOnly: true
        debit_balance:
          type: integer
          description: Debit balance in cents
          readOnly: true
        credit_balance:
          type: integer
          description: Credit balance in cents
          readOnly: true
        period_balance:
          type: integer
          description: Period balance in cents (null if no period filter applied)
          readOnly: true
        period_balance_formatted:
          type: string
          nullable: true
          description: >-
            Formatted period balance with currency symbol (null if no period
            filter)
          readOnly: true
        has_children:
          type: boolean
          description: Whether this account has sub-accounts (nested hierarchy)
          readOnly: true
        hierarchy_level:
          type: integer
          description: Depth in account hierarchy (0 for root accounts)
          readOnly: true
        is_active:
          type: boolean
          readOnly: true
          description: Whether this account is active and accepting transactions
      required:
        - account_subtype
        - account_subtype_display
        - account_type
        - account_type_display
        - code
        - credit_balance
        - currency
        - current_balance
        - current_balance_formatted
        - debit_balance
        - has_children
        - hierarchy_level
        - id
        - is_active
        - name
        - parent_account_code
        - period_balance
        - period_balance_formatted
  securitySchemes:
    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.
    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.
    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.

````