> ## 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 disclosures > Returns every disclosure Bluum surfaces to end-users — verbatim Alpaca regulated copy, Alpaca's reference PDF library (including the High Yield Cash / FDIC Bank Sweep variants), and Bluum's platform disclosures. **No authentication required** — partners can hit this endpoint from un-authenticated screens (signup, onboarding intro) to render disclosure copy. Partners should cache the response by `version` per disclosure and re-fetch on each session boundary; when a `version` advances the partner must re-prompt the user for acknowledgement. The `text` field on `kind: verbatim_text` disclosures is regulated word-for-word copy. **Do not modify, translate, or truncate it.** Translations are permitted only if they match the source language word-for-word. ## OpenAPI ````yaml /api-reference/openapi.yaml get /disclosures 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": "_", "object": "", "created": , "livemode": , "metadata": { ... }, ... domain fields ... } ``` List endpoints return: ```json { "object": "list", "url": "/v1/", "has_more": false, "data": [ ... ] } ``` 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: /disclosures: get: tags: - Disclosures summary: List disclosures description: | Returns every disclosure Bluum surfaces to end-users — verbatim Alpaca regulated copy, Alpaca's reference PDF library (including the High Yield Cash / FDIC Bank Sweep variants), and Bluum's platform disclosures. **No authentication required** — partners can hit this endpoint from un-authenticated screens (signup, onboarding intro) to render disclosure copy. Partners should cache the response by `version` per disclosure and re-fetch on each session boundary; when a `version` advances the partner must re-prompt the user for acknowledgement. The `text` field on `kind: verbatim_text` disclosures is regulated word-for-word copy. **Do not modify, translate, or truncate it.** Translations are permitted only if they match the source language word-for-word. operationId: listDisclosures parameters: - name: source in: query required: false description: Filter by source. Omit for all. schema: type: string enum: - alpaca - bluum - name: route in: query required: false description: | Filter by onboarding route. `us` returns disclosures whose route is `us` OR `all`; same for `international`. `all` (default) returns every disclosure. schema: type: string enum: - all - us - international default: all - name: step in: query required: false description: | Filter to the disclosures the partner should surface at a specific point in the onboarding / enrollment flow. schema: type: string enum: - step_6_affiliations - step_7_w8_certification - step_9_broker_agreements - step_12_post_account - step_hyc_enrollment - step_fixed_income_enrollment - platform_signup - name: requires_acknowledgement in: query required: false description: | `true` returns only disclosures the partner must capture an explicit acknowledgement for (checkbox / "I Agree" button). `false` returns reference-only disclosures. schema: type: boolean responses: '200': description: Disclosure list. content: application/json: schema: allOf: - $ref: '#/components/schemas/ListEnvelope' - type: object properties: data: type: array items: $ref: '#/components/schemas/Disclosure' examples: hyc: summary: HYC enrollment disclosures (filtered) value: object: list url: /v1/disclosures has_more: false data: - object: disclosure id: hyc_non_shariah_new_customer_ack version: '2026-05-23' source: alpaca kind: verbatim_text route: us step: step_hyc_enrollment title: >- HYC enrollment acknowledgement — new customer (Non-Shariah) text: > I have read, understood, and agree to be bound by Alpaca Securities LLC and Bluum Invest LLC account terms, and all other terms, disclosures and disclaimers applicable to me, as referenced in the [Alpaca Customer Agreement](https://files.alpaca.markets/disclosures/library/AcctAppMarginAndCustAgmt.pdf). I also acknowledge that I have been presented the [Alpaca Securities LLC Bank Sweep Program Terms and Conditions](https://files.alpaca.markets/disclosures/library/FDICSweepProgramTermsAndConditions.pdf). links: - text: Alpaca Customer Agreement url: >- https://files.alpaca.markets/disclosures/library/AcctAppMarginAndCustAgmt.pdf - text: >- Alpaca Securities LLC Bank Sweep Program Terms and Conditions url: >- https://files.alpaca.markets/disclosures/library/FDICSweepProgramTermsAndConditions.pdf requires_acknowledgement: true agreement_key: null source_reference: >- Tech Sign Off - Bluum.xlsx, High Yield Cash 1.0 (new customer onboarding) + 2.0 (correct hyperlinks present on enrollment screen) security: [] 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' Disclosure: type: object required: - object - id - version - source - kind - route - step - title - requires_acknowledgement properties: object: type: string enum: - disclosure id: type: string description: Stable identifier referenced when recording an acceptance. example: hyc_non_shariah_new_customer_ack version: type: string description: | Revision tag. Partners detect copy changes by comparing this against the version they last presented to the user. example: '2026-05-23' source: type: string enum: - alpaca - bluum description: Whether the disclosure originates from Alpaca or from Bluum. kind: type: string enum: - verbatim_text - pdf_link - html description: | `verbatim_text` — `text` holds copy the partner must render word-for-word. `pdf_link` — `url` points to the canonical PDF. `html` — `url` points to an HTML page. route: type: string enum: - all - us - international description: Onboarding route this disclosure applies to. step: type: string enum: - step_6_affiliations - step_7_w8_certification - step_9_broker_agreements - step_12_post_account - step_hyc_enrollment - step_fixed_income_enrollment - platform_signup description: | The point in the partner UI where this disclosure must be surfaced. `step_hyc_enrollment` is the FDIC Sweep program enrollment screen. `step_fixed_income_enrollment` is the bond / treasury risk disclosure shown before a partner allows the user's first fixed-income order. title: type: string description: Human-readable title for partner UIs (not regulated copy). text: type: string nullable: true description: | **Markdown.** Verbatim regulated text the partner must display unchanged. Present only when `kind=verbatim_text`. Translations are permitted only if they match the plain-text rendering word-for-word. References to named documents (e.g. *Alpaca Customer Agreement*, FDIC Bank Sweep T&Cs) are embedded inline using standard markdown link syntax `[text](url)` so partners can pass the body through any markdown renderer and get clickable links with no extra wiring. The structured `links` array below mirrors the same data for partners that prefer to skip markdown — both are kept in lockstep. **Plain-text fallback:** if you don't render markdown, strip the `[](url)` syntax (keep the bracket contents) to recover Alpaca's word-for-word regulated copy. url: type: string format: uri nullable: true description: >- Canonical URL for `pdf_link` / `html` disclosures, or the underlying PDF for `verbatim_text` disclosures that also have a printable form. links: type: array description: | References named in the body of a `verbatim_text` disclosure that the partner must surface as clickable links from the enrollment screen. Each entry's `text` matches a substring of `text` verbatim — partners do a literal find-and-replace to wrap the substring in an anchor tag. For example, the HYC enrollment acknowledgement names both "Alpaca Customer Agreement" and "Alpaca Securities LLC Bank Sweep Program Terms and Conditions"; both must be reachable from the screen per Tech Sign Off HYC 2.0. Absent on `pdf_link` / `html` disclosures (the single `url` covers those). items: type: object required: - text - url properties: text: type: string description: >- Substring of `text` to render as the link's anchor (verbatim — do not paraphrase). url: type: string format: uri requires_acknowledgement: type: boolean description: | `true` if the partner must capture an explicit click ("Accept", "Enroll", or "I Agree") and record it via `POST /v1/investors/{investor_id}/disclosures/acceptances` or via the `signed_agreements[]` array on account creation. agreement_key: type: string enum: - investor_agreement - margin_disclosure_acknowledged - w8ben_certification nullable: true description: | When this disclosure corresponds to an entry in the `signed_agreements[]` array on `POST /v1/investors`, this field holds the matching key. Use it to wire the disclosure into the create-investor payload so the acknowledgement is captured at account-create time. Null for Bluum-side-only disclosures and for HYC / fixed income acknowledgements — those are persisted via the acceptances endpoint instead. source_reference: type: string description: >- Internal reference (Alpaca spreadsheet row or Bluum doc) — useful for audit. 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. 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 ````