> ## 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. # Get a single disclosure > Retrieve one disclosure by its stable `id`. Use this when the partner has cached an acceptance against a specific disclosure id and needs to refresh the copy/version. No authentication required. ## OpenAPI ````yaml /api-reference/openapi.yaml get /disclosures/{disclosure_id} 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/{disclosure_id}: get: tags: - Disclosures summary: Get a single disclosure description: | Retrieve one disclosure by its stable `id`. Use this when the partner has cached an acceptance against a specific disclosure id and needs to refresh the copy/version. No authentication required. operationId: getDisclosure parameters: - name: disclosure_id in: path required: true schema: type: string description: | The disclosure's stable id (e.g. `hyc_non_shariah_new_customer_ack`, `investor_agreement_ack`, `alpaca_library_form_crs`). responses: '200': description: Disclosure resource. content: application/json: schema: $ref: '#/components/schemas/Disclosure' '404': $ref: '#/components/responses/NotFoundError' security: [] components: schemas: 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. 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: NotFoundError: description: The requested resource could not be found. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: not_found_error code: BLUM-404-001 message: Investor not found. 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 ````