> ## 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. # Place a new investment order ## OpenAPI ````yaml /api-reference/openapi.yaml post /investors/{investor_id}/orders 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: /investors/{investor_id}/orders: post: tags: - Trading summary: Place a new investment order operationId: createOrder parameters: - $ref: '#/components/parameters/InvestorIdPath' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OrderRequest' examples: market_buy: summary: Market buy with quantity value: symbol: AAPL side: buy type: market time_in_force: day quantity: '10' extended_hours: false limit_buy: summary: Limit buy value: symbol: MSFT side: buy type: limit time_in_force: gtc quantity: '5' limit_price: '350.00' client_order_id: my-order-123 notional_buy: summary: Market buy with dollar amount value: symbol: GOOGL side: buy type: market time_in_force: day notional: '1000.00' stop_loss: summary: Stop loss value: symbol: TSLA side: sell type: stop time_in_force: gtc quantity: '20' stop_price: '200.00' trailing_stop: summary: Trailing stop value: symbol: NVDA side: sell type: trailing_stop time_in_force: gtc quantity: '15' trail_percent: '5.0' bond_limit_buy: summary: US Treasury bond limit buy value: symbol: 912797MU8 side: buy type: limit time_in_force: day quantity: '10000' limit_price: '99.875' responses: '201': description: Order accepted by the system. content: application/json: schema: $ref: '#/components/schemas/Order' examples: pending_order: summary: Order pending value: id: ord_01j9x8m2k7qpzwv3t5r6y8n0ab object: order created: 1748390400 livemode: false metadata: {} investor_id: inv_01j9x8m2k7qpzwv3t5r6y8n0cd symbol: AAPL currency: USD side: buy type: market time_in_force: day quantity: '10' status: pending filled_quantity: '0' remaining_quantity: '10' average_price: '0.00' submitted_at: '2026-05-11T14:30:00Z' filled_at: null cancelled_at: null failure_reason: null '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NotFoundError' components: parameters: InvestorIdPath: name: investor_id in: path required: true schema: type: string description: Prefixed public id of the investor (e.g. `inv_…`). schemas: OrderRequest: type: object required: - symbol - side - type - time_in_force properties: symbol: type: string description: The ticker symbol of the asset (e.g., AAPL). example: AAPL market: type: string description: Market identifier (e.g., "NASDAQ", "NYSE"). Optional. example: NASDAQ isin: type: string description: International Securities Identification Number. Optional. example: US0378331005 figi: type: string description: Financial Instrument Global Identifier. Optional. example: BBG000B9XRY4 class: type: string description: | Optional asset class hint (e.g. `bond`, `equity`, `treasury`). Mirrors the `class` field on the asset detail response. When `bond`, the resolver accepts the `symbol` field as a CUSIP on fallback — ticker collisions like ABBNVX (two distinct ABB Finance bonds sharing the same ticker) cannot be disambiguated by symbol alone. example: bond country: type: string description: >- Optional ISO country code (e.g. `us`) to help disambiguate cross-listed assets. example: us quantity: type: string description: >- Quantity of shares to trade (required if notional not provided, required for sell orders). example: '5' notional: type: string description: >- Dollar amount to trade (required if quantity not provided, only for buy market orders). example: '1000.00' side: type: string enum: - buy - sell description: Whether to buy or sell the asset. example: buy type: type: string enum: - market - limit - stop - stop_limit - trailing_stop description: | Order type: - market: Executes immediately at current market price - limit: Sets a specific price limit - stop: Stop loss order that triggers at stop price - stop_limit: Stop order with a limit price - trailing_stop: Trailing stop order example: limit time_in_force: type: string enum: - day - gtc - opg - cls - ioc - fok description: > How long the order remains active: - day: Expires at end of trading day - gtc: Good Till Cancelled - remains active until filled or cancelled - opg: Opening - executes at market open - cls: Closing - executes at market close - ioc: Immediate or Cancel - fills immediately or cancels - fok: Fill or Kill - fills completely or cancels example: day limit_price: type: string description: >- Price limit for limit/stop_limit orders (required when type is 'limit' or 'stop_limit'). example: '175.00' stop_price: type: string description: >- Stop price for stop/stop_limit orders (required when type is 'stop' or 'stop_limit'). example: '170.00' trail_percent: type: string description: >- Trail percentage for trailing stop orders (required for trailing_stop if trail_price not provided). example: '2.5' trail_price: type: string description: >- Trail price for trailing stop orders (required for trailing_stop if trail_percent not provided). example: '5.00' extended_hours: type: boolean default: false description: Whether to allow extended hours trading. example: false client_order_id: type: string description: Optional client-provided identifier for tracking the order. example: limitorder123 commission: type: string description: Commission amount to charge (optional). example: '1.00' commission_type: type: string enum: - notional - per_share - bps description: > Commission calculation method: - notional: Charge commission on a per order basis (default) - per_share: Charge commission on a per-share/contract basis, pro rated - bps: Percent commission in basis points (up to 2 decimal places) example: notional wallet_currency: type: string enum: - USD - NGN - GBP - EUR - KES description: | Wallet currency to fund or receive trade proceeds. When omitted, defaults to USD (default wallet). example: NGN settlement_date: type: string format: date description: | Settlement date for bond orders (ISO `yyyy-mm-dd`). Optional — defaults to T+1 for treasuries / T+2 for corporates when omitted, and is ignored for non-bond orders. For bonds, `quantity` carries face value (multiples of `min_increment`), `limit_price` is % of par (e.g. `99.875`), and `time_in_force` must be `day`. example: '2026-05-22' Order: description: | Trading order resource. Flat shape: `quantity` not `qty`, `failure_reason` not `reject_reason`, `investor_id` not `account_id`, Bluum-native status vocab. The envelope `created` field is the canonical creation timestamp; `submitted_at` mirrors when the order was submitted to the custodian (null until submission). allOf: - $ref: '#/components/schemas/ResourceEnvelope' - type: object properties: investor_id: type: string description: Prefixed public id of the investor. example: inv_01j9x8m2k7qpzwv3t5r6y8n0ab symbol: type: string example: AAPL class: type: string description: Asset class name (e.g. equity, bond, etf). example: equity currency: type: string example: USD quantity: type: string description: Quantity of shares ordered (for quantity-based orders). example: '5' notional: type: string description: Notional amount ordered (for notional-based orders). example: '1000.00' side: type: string enum: - buy - sell type: type: string enum: - market - limit - stop - stop_limit - trailing_stop time_in_force: type: string description: | FIX-standard time-in-force; not Alpaca-coined. enum: - day - gtc - opg - cls - ioc - fok limit_price: type: string stop_price: type: string trail_percent: type: string trail_price: type: string extended_hours: type: boolean client_order_id: type: string status: type: string description: Bluum-native order status. enum: - pending - filled - partial - cancelled - failed example: pending filled_quantity: type: string example: '0' remaining_quantity: type: string example: '5' average_price: type: string commission: type: string commission_type: type: string enum: - notional - per_share - bps submitted_at: type: string format: date-time nullable: true description: >- When the order was submitted to the custodian. Null until submission. filled_at: type: string format: date-time nullable: true cancelled_at: type: string format: date-time nullable: true failure_reason: type: string nullable: true settlement_date: type: string format: date nullable: true description: | Settlement date Alpaca will use for bond orders, when known. Bluum does not specify or override this — Alpaca chooses based on the bond's subtype. Null for non-bond orders or until Alpaca confirms. example: '2026-05-22' bond: $ref: '#/components/schemas/OrderBondExecutionDetails' 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. OrderBondExecutionDetails: type: object description: | Fixed-income execution detail. Populated only when the underlying asset is a bond. Prices are % of par; accrued and face_value are in `currency`. properties: clean_price: type: string description: Clean price at execution, % of par. example: '99.875' dirty_price: type: string description: Dirty price at execution (clean + accrued), % of par. example: '100.342' accrued_interest: type: string description: Accrued interest paid to seller per 100 face value. example: '0.467' face_value: type: string description: Face value of the trade (matches `quantity`). example: '10000' yield_at_execution: type: string description: Yield realized at execution, decimal. example: '0.0475' 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: BadRequestError: description: The request was malformed or failed validation. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request_error code: BLUM-400-002 message: Required field 'symbol' is missing. param: symbol 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. 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 ````