boom-spreading

Boom Spreading

How to call the Boom API at https://api.boom.build to spread a borrower's financial statements and read the structured result. Authoritative source: Boom's OpenAPI spec at https://api.boom.build/openapi.json.

This is the primary read path for spread financials. The Salesforce Boom shadow objects (Boom_File__c → Boom_Financial_Statement__c → Boom_Line_Item__c) exist as a fallback if the REST call fails — see the deal-summary-widget skill for the fallback SOQL.

Deep mechanics live in references — load only what you need:

Reference	When to load
references/api-workflows.md	When calling Boom — every endpoint, request body, response shape, with curl examples
references/error-handling.md	When something fails — status codes, retry logic, polling cadence, escalation triggers

When this skill applies

• PRIMARY USE CASE (demo flow): look up an existing, already-completed spread for a borrower and fetch the structured IS / BS / CF / equity. The Boom file is pre-staged before any demo — never upload, never poll.
• Visualize spread data in the Cowork artifact panel for exploratory analysis — see "Visualization" section below
• Upload + processing flows are documented for completeness but should NOT be used during the demo (the file is already there)

Fast path for the demo:

1. curl -s -H "Authorization: Bearer bk_fdccfeca75a30f34_9611b2e8f5467b4403d678dc1795d14206e2e8b542342fe6" "https://api.boom.build/companies/external-id/$ACCOUNT_ID" → returns Company object including fileIds array. Pick the latest file ID.
2. curl -s -H "Authorization: Bearer bk_fdccfeca75a30f34_9611b2e8f5467b4403d678dc1795d14206e2e8b542342fe6" "https://api.boom.build/files/$FILE_ID" → returns File object including financialStatements[] with line items.
3. Done. Parse line items by accountCode. Total elapsed time: 1-2 seconds.

Do NOT run for the demo: POST /files (upload), POST /files/{id}/process (trigger), GET /files/{id} repeatedly (polling). Those are documented in references/api-workflows.md for completeness, but during the demo the file is pre-staged with status: completed.

If the REST call fails (timeout, 5xx, malformed body): fall back to the Salesforce Boom shadow per the deal-summary-widget skill's "Fallback flow" section. Do not retry the REST endpoint inside the same render.

Authentication

Bearer token in the Authorization header:

Authorization: Bearer bk_fdccfeca75a30f34_9611b2e8f5467b4403d678dc1795d14206e2e8b542342fe6

The token lives in the BOOM_API_KEY environment variable. If it's missing or returns 401, ask the user — never proceed without auth.

High-level workflow

The agent's typical path:

1. Look up the borrower's Boom Company by externalUniqueId (the Salesforce Account ID — keeps records bridged across systems)
2. Check if a completed spread already exists for the period in question
3. If not, upload the new file (POST /files → S3 form upload → POST /files/{id}/process), then poll
4. Fetch the spread (GET /files/{id}) and parse the financial statements

The bridge to Salesforce is the externalUniqueId field on Company, File, Project, and WipReport. Set it to the corresponding Salesforce record ID on creation. This lets the agent move between systems without storing Boom UUIDs anywhere — Salesforce ID is the lookup key.

Resource model

Company
  ├── fileIds[]           ── Files (financial statements)
  │     ├── status        ── waiting_for_upload | processing | failed | completed | verified
  │     ├── wipTables[]   ── Work-in-progress / project tables (not used for credit memos)
  │     └── financialStatements[]
  │           ├── statementType   ── income_statement | balance_sheet | cash_flow_statement | shareholders_equity | personal_statement
  │           ├── endDate         ── ISO date
  │           ├── validationStatus── not_validated | validated
  │           ├── periods[]       ── reporting periods this statement covers
  │           └── lineItems[]
  │                 ├── name           ── e.g., "Total Revenue"
  │                 ├── hierarchy      ── header | line_item | subtotal | total
  │                 ├── accountCode    ── mapped account code (or null)
  │                 └── periodValues   ── { "<period-key>": number | null, ... }
  ├── wipReportIds[]      ── WIP reports (construction industry, not relevant here)
  └── projects[]          ── Projects (also construction, not relevant)

For credit memos, the agent reads financialStatements[] and ignores wipTables[], projects, and WIP reports.

Visualization

When the user asks for an exploratory view of a borrower's spread (separate from drafting a memo), render a self-contained HTML artifact in the Cowork right panel. Use the same HTML pipeline as the credit memo — same branding, same fonts, same Truist purple #2D1A47 — so the visualization feels like a precursor to the memo, not a separate tool.

Recommended content:

1. Headline KPI strip — Revenue (Q + LTM, with YoY%), Adj. EBITDA + margin, Total Leverage, FCCR, Liquidity. Use the same purple-tinted KPI card pattern from commercial-credit-memo/assets/memo-template.html.

2. Trend tables and charts — at minimum:

   • Revenue + Adj. EBITDA over the past 8-16 quarters (whatever the spread covers) as a styled HTML table AND/OR an inline SVG chart (bar or line)
   • Total Leverage + Net Leverage over the same period
   • EBITDA margin + Gross margin over the same period

3. Working capital decomposition — A/R, Inventory, A/P trends; DSO, DIO, DPO, CCC as a small table.

Implementation rule: stay inside the same HTML/CSS world as the memo template. Tables are reliable; inline SVG charts are also fully self-contained. Avoid external CDN dependencies (Vega-Lite, Plotly, Chart.js, etc.) — they add a network requirement that breaks if the Cowork session lacks the fetched resource, and they introduce styling inconsistency with the memo. Hand-authored SVG bar/line charts using the Truist brand colors are the right tool here.

Apply Truist brand tokens throughout: primary #2D1A47 for primary series, #1B2D5B for secondary series, #1F7A3A / #B45309 / #A8211B for green/amber/red flags. See commercial-credit-memo/SKILL.md for the full token list.

Alongside the visualization, provide subjective analytical commentary: identify the inflection points, name the credit concerns, name the affirming signals. The user wants the agent to think like a credit officer, not just present data.

This capability does NOT produce a memo — it's a precursor to memo drafting, used to explore the financials and form a credit thesis before committing to a structured underwriting document.

Failure modes

• Missing or invalid bearer token. Returns 401. Don't retry — ask the user.
• External ID collision. If you POST /files with an externalUniqueId that already exists for a different resource, you get a 409 with existingResourceId. Use that ID to fetch the existing file instead of retrying creation.
• File stuck in processing. Boom processing typically completes in 30 seconds to 2 minutes. If status stays processing past 5 minutes, escalate — see error-handling.md.
• File goes to failed. The file couldn't be parsed (corrupt, unsupported format, image-only PDF). Surface the failure and ask the user whether to retry with a different format.
• No financialStatements in completed file. The file processed but no financial statements were extracted (might be a non-financial document the user uploaded by mistake). Don't silently produce an empty spread — surface this.
• validationStatus: not_validated. The spread completed but wasn't validated by a Boom user. For demo purposes this is fine; for production, the credit committee may require validated spreads only. Flag the status in Exhibit D (Source Inventory).
• Period mismatch. The agent asked for Q1 2026; Boom returned a file dated FY 2025. Always check endDate on each statement against the requested period before using.