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

# List all investors for the authenticated tenant



## OpenAPI

````yaml /api-reference/openapi.yaml get /investors
openapi: 3.0.0
info:
  title: Bluum Finance Investment API
  version: 1.0.0
  description: >
    The Bluum Finance API provides embeddable investment experiences, allowing
    fintech partners to manage investor accounts, facilitate trading, handle
    document uploads, and manage wallet operations.


    ### Response conventions


    Every resource response carries a small, consistent set of envelope keys

    followed by domain fields:


    ```json

    {
      "id": "<prefix>_<base32>",
      "object": "<resource>",
      "created": <unix_seconds>,
      "livemode": <boolean>,
      "metadata": { ... },
      ... domain fields ...
    }

    ```


    List endpoints return:


    ```json

    {
      "object": "list",
      "url": "/v1/<resource>",
      "has_more": false,
      "data": [ <resource>... ]
    }

    ```


    Errors are wrapped in:


    ```json

    {
      "error": {
        "type": "invalid_request_error",
        "code": "BLUM-400-001",
        "message": "...",
        "param": "tax_id"
      }
    }

    ```


    See `ResourceEnvelope`, `ListEnvelope`, and `ErrorEnvelope` in

    `shared-schemas.yaml` for the full schemas.


    ### Product entitlements


    Core investing (accounts, funding, trading, positions, documents,

    webhooks) is available to every tenant. Three surfaces are add-on products

    that must be enabled for your tenant before use:


    - **Market Data** — `/v1/market-data/*`

    - **Cash Management** — `/v1/cash-management/*`


    Calling a disabled product returns HTTP `403` with the legacy

    `{ "status": "error", "code": "PRODUCT_NOT_ENABLED", "message": "..." }`

    body (not the standard error envelope). Contact your Bluum account manager

    to enable a product.


    ### Field naming


    - snake_case throughout (no camelCase)

    - `email` / `phone` (not `email_address` / `phone_number`)

    - `first_name` / `middle_name` / `last_name` (not `given_name` /
    `family_name`)

    - `address: { street: [string], unit?, city, state?, postal_code?, country
    }`
      (the `street` array form preserves multi-line addresses; ISO 3166-1
      alpha-2 country code on `address.country` and on the top-level
      `country_of_*` fields)
    - `quantity` (not `qty`)

    - Status enums are lowercase Bluum-native vocabulary (e.g. `pending` /
    `filled` / `cancelled` / `failed`)


    Regulatory vocabulary (CAIS / FINRA / IRS / FATF) is preserved verbatim

    (e.g. `tax_id_type`, `country_of_tax_residence`, `is_politically_exposed`,

    `funding_source`).


    ### Terminology


    The investor resource lives at `/v1/investors`. Path parameter is

    `investor_id`.


    ### Asset classification


    Assets carry a canonical `(class, country)` pair:

    - `class`: `equity` | `etf` | `bond` | `bill` | `note` | `mutual_fund` |
      `derivative` | `cryptocurrency` | `commodity` | `real_estate` | `cash`
    - `country`: ISO 3166-1 alpha-2, lower-case (`us`, `ng`, …). Null for
      country-agnostic instruments (most crypto).

    ### Fixed income (bonds)


    Bond orders use the same `POST /v1/investors/{investor_id}/orders`

    endpoint as equities, with bond-specific semantics:

    - `quantity` carries **face value** (e.g. `"10000"` for $10k face),
      and must be a multiple of the bond's `min_increment`.
    - `limit_price` is quoted as **% of par** (e.g. `"99.875"` = 99.875%
      of face value).
    - `settlement_date` is optional; defaults to T+1 for US treasuries
      and T+2 for corporates.
    - Bond quote responses (`/v1/market-data/assets/{symbol}/quote`)
      include a `bond` block with clean/dirty price, accrued interest,
      and yield to maturity.

    Bond trading must be explicitly enabled on the tenant before orders

    will route. Contact Bluum support to flip `fixedIncomeEnabled`.


    ### Authentication


    HTTP Basic Authentication. **API Key** is the username, **API Secret** is

    the password. Base64-encode `API_KEY:API_SECRET` and send in the

    `Authorization` header.
servers:
  - url: https://api.bluumfinance.com/v1
    description: Production Environment
  - url: https://sandbox.api.bluumfinance.com/v1
    description: Sandbox/Testing Environment
  - url: https://service.bluumfinance.com/v1
    description: Production Environment (legacy alias)
  - url: https://test-service.bluumfinance.com/v1
    description: Sandbox/Testing Environment (legacy alias)
security:
  - BluumApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: Investors
    description: Create and manage investor accounts, wallets, and transactions.
  - name: API Keys
    description: Mint, list, and revoke investor-scoped API keys for programmatic access.
  - name: Compliance
    description: Investor compliance workflows, KYC checks, and document submissions.
  - name: Transfers
    description: Deposit and withdrawal operations for investor wallets.
  - name: Funding Sources
    description: Connect and manage external funding sources (Plaid, bank accounts).
  - name: Trading
    description: Place, list, and cancel investor orders.
  - name: Positions
    description: View investor portfolio positions.
  - name: Assets
    description: Search and retrieve asset reference data.
  - name: Document Management
    description: Upload, list, and download documents.
  - name: Markets
    description: Market reference data, status, calendar, and halts.
  - name: Market Data
    description: Real-time quotes, snapshots, and historical bars (paywalled product).
  - name: Webhooks
    description: Register and manage webhook endpoints for event delivery.
  - name: Disclosures
    description: >-
      Partner-facing disclosure library (verbatim regulated copy, PDFs) +
      per-investor acceptance trail.
  - name: Cash Sweep
    description: >-
      High Yield Cash (HYC) / FDIC Bank Sweep enrollment, tier management, and
      interest reporting.
  - name: Cash Management
    description: >-
      Multi-currency, zero-day-liquidity yield on cash — programs, eligibility,
      enrollment, sweeps, withdrawals, earnings.
paths:
  /investors:
    get:
      tags:
        - Investors
      summary: List all investors for the authenticated tenant
      operationId: listAccounts
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
          description: Maximum number of investors to return.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Number of investors to skip for pagination.
      responses:
        '200':
          description: List of investors.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ListEnvelope'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Investor'
              examples:
                success:
                  summary: One active investor
                  value:
                    object: list
                    url: /v1/investors
                    has_more: false
                    data:
                      - id: inv_01j9x8m2k7qpzwv3t5r6y8n0ab
                        object: investor
                        created: 1747776000
                        livemode: false
                        metadata: {}
                        status: active
                        account_type: individual
                        management_type: self_directed
                        tax_advantaged: false
                        tax_designation: null
                        account_number: '968430933'
                        currency: USD
                        balance: '1000.00'
                        buying_power: '10000.00'
                        cash_withdrawable: '5000.00'
                        last_equity: '5000.00'
                        crypto_status: null
                        trading_type: cash
                        first_name: John
                        middle_name: null
                        last_name: Doe
                        date_of_birth: '1980-01-01'
                        email: john.doe@example.com
                        phone: '+15555555555'
                        address:
                          street:
                            - 123 Main St
                          unit: null
                          city: Berkeley
                          state: CA
                          postal_code: '94704'
                          country: US
                        tax_id_type: SSN
                        country_of_tax_residence: US
                        country_of_citizenship: US
                        country_of_birth: US
                        funding_source:
                          - employment_income
                        is_control_person: false
                        is_affiliated_exchange_or_finra: false
                        is_affiliated_exchange_or_iiroc: null
                        is_politically_exposed: false
                        immediate_family_exposed: false
                        employment_status: employed
                        employer_name: Acme Inc
                        employer_address: 1 Tech Way, Berkeley, CA
                        employment_position: Engineer
                        signed_agreements:
                          - type: investor_agreement
                            signed_at: '2026-01-15T10:30:00.000Z'
                            ip_address: 203.0.113.42
                        trusted_contact: null
                        portfolios: []
        '401':
          $ref: '#/components/responses/UnauthorizedError'
components:
  schemas:
    ListEnvelope:
      type: object
      description: |
        List envelope. `data` holds the page of items;
        each item is itself wrapped in a ResourceEnvelope.
      required:
        - object
        - url
        - has_more
        - data
      additionalProperties: true
      properties:
        object:
          type: string
          enum:
            - list
        url:
          type: string
          description: The endpoint path that produced this list.
          example: /v1/investors/inv_…/deposits
        has_more:
          type: boolean
          description: Whether more results exist beyond `data`.
          example: false
        data:
          type: array
          items:
            $ref: '#/components/schemas/ResourceEnvelope'
    Investor:
      description: |
        The investor (account) resource. flat: regulatory fields are
        flat at the top level; only `address`, `signed_agreements[]`, and
        `trusted_contact` retain meaningful nesting. The Alpaca-style
        `contact` / `identity` / `disclosures` block grouping is intentionally
        absent.
      allOf:
        - $ref: '#/components/schemas/ResourceEnvelope'
        - type: object
          properties:
            status:
              type: string
              enum:
                - onboarding
                - under_review
                - awaiting_documents
                - active
                - suspended
                - closed
                - declined
                - setup_failed
              description: Bluum-native account status.
              example: onboarding
            account_type:
              type: string
              enum:
                - individual
                - joint
                - corporate
              example: individual
            management_type:
              type: string
              enum:
                - self_directed
                - advised
              example: self_directed
            tax_advantaged:
              type: boolean
              example: false
            tax_designation:
              type: string
              nullable: true
            account_number:
              type: string
              nullable: true
            currency:
              type: string
              example: USD
            balance:
              type: string
              example: '0.00'
            buying_power:
              type: string
              description: >-
                Available buying power from the custodian brokerage account.
                Defaults to "0" when no custodian account exists yet.
              example: '10000.00'
            cash_withdrawable:
              type: string
              description: >-
                Amount of cash available for withdrawal from the custodian
                brokerage account. Defaults to "0" when no custodian account
                exists yet.
              example: '5000.00'
            last_equity:
              type: string
              example: '0.00'
            crypto_status:
              type: string
              nullable: true
            trading_type:
              type: string
              enum:
                - cash
                - margin
                - null
              nullable: true
            high_yield_cash_status:
              type: string
              description: High-Yield-Cash enrollment lifecycle for this account.
              enum:
                - not_registered
                - pending
                - active
                - unenrolled
              example: active
            high_yield_cash_status_at:
              type: string
              format: date-time
              nullable: true
              description: >-
                Timestamp of the transition into the current HYC status (null
                when not_registered).
            first_name:
              type: string
              example: Jane
            middle_name:
              type: string
              nullable: true
            last_name:
              type: string
              example: Doe
            date_of_birth:
              type: string
              format: date
              nullable: true
              example: '1990-01-01'
            email:
              type: string
              format: email
              example: jane@example.com
            phone:
              type: string
              nullable: true
              example: '+15555550123'
            address:
              type: object
              description: |
                Address record. `street` is an array of one or more street
                lines (multi-line addresses keep one entry per line).
              properties:
                street:
                  type: array
                  items:
                    type: string
                  example:
                    - 123 Market St
                unit:
                  type: string
                  nullable: true
                city:
                  type: string
                  nullable: true
                state:
                  type: string
                  nullable: true
                postal_code:
                  type: string
                  nullable: true
                country:
                  type: string
                  description: ISO 3166-1 alpha-2.
                  nullable: true
                  example: US
            tax_id_type:
              type: string
              enum:
                - SSN
                - ITIN
                - EIN
                - SIN
                - NINO
                - TFN
                - VAT
                - TIN
                - UTR
                - PAN
                - NIN
                - KRA_PIN
                - OTHER
              nullable: true
            country_of_tax_residence:
              type: string
              description: ISO 3166-1 alpha-2.
              nullable: true
            country_of_citizenship:
              type: string
              description: ISO 3166-1 alpha-2.
              nullable: true
            country_of_birth:
              type: string
              description: ISO 3166-1 alpha-2.
              nullable: true
            funding_source:
              type: array
              items:
                type: string
                enum:
                  - employment_income
                  - investments
                  - inheritance
                  - business_income
                  - savings
                  - family
                  - other
            is_control_person:
              type: boolean
            is_affiliated_exchange_or_finra:
              type: boolean
            is_affiliated_exchange_or_iiroc:
              type: boolean
              nullable: true
            is_politically_exposed:
              type: boolean
            immediate_family_exposed:
              type: boolean
            employment_status:
              type: string
              enum:
                - employed
                - unemployed
                - student
                - retired
              nullable: true
            employer_name:
              type: string
              nullable: true
            employer_address:
              type: string
              nullable: true
            employment_position:
              type: string
              nullable: true
            signed_agreements:
              type: array
              items:
                type: object
                required:
                  - type
                  - signed_at
                properties:
                  type:
                    type: string
                    description: |
                      Bluum-native agreement key. Translation to Alpaca's
                      wire keys (customer_agreement / account_agreement /
                      margin_agreement) happens internally.
                    enum:
                      - investor_agreement
                      - margin_disclosure_acknowledged
                      - w8ben_certification
                    example: investor_agreement
                  signed_at:
                    type: string
                    format: date-time
                  ip_address:
                    type: string
                    nullable: true
            trusted_contact:
              type: object
              nullable: true
              properties:
                first_name:
                  type: string
                last_name:
                  type: string
                email:
                  type: string
                  format: email
                phone:
                  type: string
                  nullable: true
            portfolios:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  status:
                    type: string
                  currency:
                    type: string
                    nullable: true
                  createdAt:
                    type: string
                    format: date-time
                  updatedAt:
                    type: string
                    format: date-time
            compliance_checks:
              type: array
              nullable: true
              items:
                $ref: '#/components/schemas/ComplianceCheckResponse'
    ResourceEnvelope:
      type: object
      description: |
        Resource envelope. Domain fields are spread after the
        envelope keys (`id`, `object`, `created`, `livemode`, `metadata`).
        Some Bluum-original resources may emit only `object` + `livemode`
        without `id` / `created` (e.g. one-off action results).
      required:
        - object
        - livemode
      additionalProperties: true
      properties:
        id:
          type: string
          description: Prefixed public id (e.g. `inv_…`, `ord_…`, `dep_…`).
          example: inv_01j9x8m2k7qpzwv3t5r6y8n0ab
        object:
          type: string
          description: The resource type discriminator.
          example: investor
        created:
          type: integer
          nullable: true
          description: Unix-seconds timestamp of resource creation.
          example: 1747776000
        livemode:
          type: boolean
          description: |
            Whether this resource was created against a live API key.
            Test-mode keys always return `false`.
          example: false
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Partner-set key/value map for cross-referencing.
    ComplianceCheckResponse:
      type: object
      properties:
        workflow_id:
          type: string
          description: The compliance workflow this check belongs to.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        check_type:
          type: string
          enum:
            - identity_verification
            - tax_id_verification
            - screening
            - risk_assessment
            - business_verification
          description: The type of compliance check performed.
          example: identity_verification
        status:
          type: string
          enum:
            - pending
            - clear
            - failed
            - review_required
            - error
          description: >
            Current status of the check:

            - `pending` — Async verification in progress; use `verification_url`
            or `verification_token` for user completion.

            - `clear` — Verification passed.

            - `failed` — Verification failed.

            - `review_required` — Manual review needed (e.g., potential
            PEP/sanctions match).

            - `error` — Provider error during verification.
          example: pending
        provider:
          type: string
          nullable: true
          description: >-
            The verification provider handling this check (e.g.,
            persona-identity, persona-taxid, dojah).
          example: persona-identity
        external_id:
          type: string
          nullable: true
          description: Provider-specific reference ID for the verification.
          example: inq_abc123def456
        verification_url:
          type: string
          nullable: true
          description: |
            User-facing verification URL for async checks, when available.
          example: https://withpersona.com/verify?inquiry-id=inq_abc123def456
        verification_token:
          type: string
          nullable: true
          description: >
            Provider token or SDK configuration for client-side verification,
            when available.
          example: null
    ErrorEnvelope:
      type: object
      description: |
        Error envelope. The Bluum-specific `BLUM-XXX-XXX`
        code is carried in `error.code`; `error.type` is the broad
        category clients branch on.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - code
            - message
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - permission_error
                - not_found_error
                - conflict_error
                - idempotency_error
                - rate_limit_error
                - api_error
              example: invalid_request_error
            code:
              type: string
              description: The Bluum-specific error code.
              example: BLUM-400-001
            message:
              type: string
              description: Developer-facing message.
            param:
              type: string
              description: Field path of the invalid input.
              example: tax_id
            doc_url:
              type: string
              format: uri
              example: https://docs.bluum.finance/errors/BLUM-400-001
            request_log_url:
              type: string
              format: uri
              description: Deep link to the request log in the partner dashboard.
  responses:
    UnauthorizedError:
      description: Authentication information is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error:
              type: authentication_error
              code: BLUM-401-001
              message: Missing or invalid Authorization header.
  securitySchemes:
    BluumApiKeyAuth:
      type: http
      scheme: basic
      description: >
        HTTP Basic Authentication using the **API Key** as username and **API
        Secret** as password.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT token from Clerk authentication

````