📊 MoneyThumb → HubSpot Field Map

1. Overview #

MoneyThumb (PDF Insights TP, API v1.5) ingests bank statement PDFs and a Plaid asset report and returns a structured scorecard of revenue metrics, account summaries, debt indicators, and per-statement detail. It is a downstream underwriting analysis subsystem — never runs during intake.

Once a deal has classified bank statements, the pipeline creates an MT app, uploads PDFs, polls for results, then fans out to:

• Deal properties — orchestration status, revenue statistics (production-final), 3m/6m/all aggregates, and _extracted raw values.
• Bank Statement custom object (2-37801779) — one record per (statement-month × account).
• MCA Position custom object (2-38036513, internal name lender_metrics) — one consolidated record per lender.
• UW Documents custom object (2-56466936) — four MT file outputs (CSV, Excel scorecard, log, summary PDF).
• Associated Company — gap-fill for DBA, address, ZIP+4, primary bank.

Two parallel write paths exist (see §2). Property catalog reference: reference/hubspot/hubspot_properties_deals.json.

2. Sync mechanism summary #

MT API → moneyThumbWebhook OR pollMoneyThumbResults
       → results stored at deals/{dealId}/moneythumb_results/latest
       → syncMoneyThumbToHubSpot()  (full-refresh orchestrator)
            ├─ clearHubspotDeal()                    [archive prior bank statements + MCA positions, blank revenue props]
            ├─ moneythumbService.makeExcel()         [fetch xlsx scorecard]
            ├─ upload JSON + XLS to GCS              [public URLs]
            ├─ syncBankStatementsToHubSpot()         [batch upsert by tid]
            ├─ syncMcaPositionsToHubSpot()           [batch upsert by lender_name]
            ├─ extractRevenueStatistics() + computeMoneythumbAggregates()
            │       → PATCH deals/{id}: revenue stats + 3m/6m/all aggregates + average_monthly_revenue__final_
            ├─ computeCompanyAddressFromAppinfo()    [PATCH company: only fill empty fields]
            └─ enrichmentService.enrichFields()      [Firestore-side enrichment, conf 0.95]

Parallel path (poller only):
       → extractAndStoreDealProperties()             [Firestore deals/{id}.extractedFields.*]
       → syncExtractedFieldsToHubSpot()              [PATCH *_extracted props]
       → enrichCompanyFromMoneyThumb()               [DBA + address gap-fill on company]
       → processMoneyThumbFiles()                    [4 UW Documents]

Practical implication: the canonical MT sync is the orchestrator. The poller writes a strictly smaller set of fields (the _extracted family).

3. RAW EXTRACTED _extracted suffix #

Set by syncExtractedFieldsToHubSpot() (poller + manual sync only). Source = Firestore deals/{id}.extractedFields.*. UW-editable; locked fields are skipped on next sync.

4. DERIVED / SYNCED production-final #

Written by syncMoneyThumbToHubSpot() orchestrator in a single PATCH at syncMoneyThumbResultsToHubSpot.js:234.

4a. Status / orchestration

moneythumb_app_status enum domain: Not Ready for Moneythumb, Ready for Moneythumb, App Created, Upload Started, Upload Complete, Results Synced, Results Refreshed, Statements Cleared/Reset, Error. Bold values are written by the orchestrator/clear; intermediates are written upstream during upload.

4b. Revenue Statistics (deal-level)

Set by extractRevenueStatistics(). Source = scorecard.revenue_statistics[] rows keyed by label.

4c. Aggregates (3m / 6m / all)

Set by computeMoneythumbAggregates(). Source = per-month combined_account_summary array (oldest → newest).

All numeric values rounded to 2 decimal places via round2(). null results dropped from PATCH.

5. MT Reports as UW Documents 2-56466936 #

Created by processMoneyThumbFiles() via syncDocumentToHubSpot(). All four collapse to document_type = 'MoneyThumb Report'.

Rollup: number_of_uw_docs__moneythumb counts these. Final HubSpot UW Document name format: {dealId}-MoneyThumb Report.{ext} with (N) suffix on duplicates.

6. Bank Statement object 2-37801779 #

Created by syncBankStatementsToHubSpot(). One record per (account, statement_month). Existing records matched by moneythumb_tid__base_ and upserted via batch.

Rollup feeders: source for the deal-level n3_month_avg_true_revenue and n4_month_avg_true_revenue rollups (formulas defined in HubSpot UI).

7. MCA Position object 2-38036513 (lender_metrics) #

Created by syncMcaPositionsToHubSpot(). One consolidated record per lender per deal. Existing records matched by moneythumb_app_id + associated_deal_id.

Source aggregation merges three MT inputs: mca_companies[] (totals), monthly_mca[] (per-month), and sections.mca.data (flattened detail). Per-lender aggregates sum monthly amounts/counts, falling back to mca_companies totals when monthly data is missing.

Rollup feeder: source for number_of_associated_mca_positions.

8. HubSpot rollups not written by code #

Computed by HubSpot itself. The integration relies on them but never PATCHes them.

Implication: rollup propagation is asynchronous — after the orchestrator completes, rollups may briefly show stale values.

9. Status / state properties orchestration #

10. Calculations end-to-end #

10a. average_monthly_revenue__final_ — the canonical "verified" revenue

MT scorecard.revenue_statistics[]
   ├─ row { label: 'True Revenue', monthly: 47235.62 }    ← preferred
   └─ row { label: 'Revenue',      monthly: 51000.00 }    ← fallback
        │
        ▼
computeMoneythumbAggregates()    [moneythumb/helpers/computeMoneythumbAggregates.js:117-124]
        │
        ▼
PATCH deals/{id} { average_monthly_revenue__final_: 47235.62 }
        │
        ▼
offer-calculator GET /getDealData    [functions/offerCalculator/index.js:582,638]
        │
        ▼
formData.monthlyRevenue = parseFloat(deal.average_monthly_revenue__final_) || 0
        │
        ▼
calculator.js → suggested_offer_amount, recommended_term, etc.

This is the field that drives the offer calculator's monthly revenue input for both Cobalt and Magenta. The lone numeric MT field consumed by the calc.

Note: average_monthly_revenue__sync_ (group self-reported) is the self-reported revenue, never written by MT code. The offer calculator uses __final_.

10b. cobalt_funding_position

MCA Position custom-object records (created by syncMcaPositionsToHubSpot)
        │  (HubSpot async rollup)
        ▼
deal.number_of_associated_mca_positions  (calculation_rollup)
        │
        ▼
deriveFundingPosition(mcaCount)    [intakeRequiredDocumentStatus.js:35]
        │
        ▼
position = min(mcaCount + 1, 6)  →  '1'..'6'
        │
        ▼
recomputeAndSyncIntakeRequiredDocumentStatus()    [intakeRequiredDocumentStatus.js:165-181]
        │
        ▼
PATCH deals/{id} { cobalt_funding_position: <derived> }   ← ONLY when current value is empty
        │
        ▼
offer-calculator: fundingPosition = parseInt(deal.cobalt_funding_position) || 1
        │
        ▼
HubDB cfs_funding_position lookup → term_deduction, max_term, sp_deduction

Critical rule: UW may set cobalt_funding_position manually. The derivation must never overwrite a non-empty value. Regression test at intakeRequiredDocumentStatus.test.js:334.

10c. NSF / overdraft / negative-day chain

The Firestore extracted-fields path also computes a synthetic bankAnalysisRiskScore + bankAnalysisRiskFactors in extractFinancialMetrics(), but these go to Firestore only — NOT pushed to any HubSpot deal property by current sync handlers.

11. Consumers / dependents #

11a. Offer Calculator

• average_monthly_revenue__final_ — sole MT-derived input for Cobalt CFS + Magenta MF (configs/cobalt.config.js:73, configs/magenta.config.js:70, index.js:582,638).
• cobalt_funding_position — input via cobalt.config.js:76, index.js:585,644. Derived from MCA-Position rollup when empty.

11b. intake_required_document_status aggregate

intakeRequiredDocumentStatus.js:80-87 requires for complete:

• All five association sub-statuses are complete
• number_of_associated_uw_docs__applications >= 1
• number_of_associated_uw_docs__bank_statements >= 3
• number_of_uw_docs__moneythumb >= 1
• moneythumb_app_status === 'Results Synced'

If MT is configured but never completes, the deal cannot reach complete intake status.

11c. Intake-time gating (matchCompanyContact)

matchCompanyContact.js:278-318 and :430-466: when the deal becomes ready for MT, set moneythumb_app_status='Ready for Moneythumb' — but only if the current value is not in the in-progress/done set. Prevents intake re-runs from regressing a completed MT workflow.

11d. Document classification

geminiClassifier.js and genkit/classifyDocument.js recognize moneythumb_report. Files matching moneythumb, scorecard, or summary_report classified directly without LLM (classifyDocuments.js:69-70).

11e. Deal-stage advancement

No code in this repo directly advances a deal stage based on MT fields. Stage advancement is HubSpot-workflow driven.

12. Firestore companion data (not HubSpot) #

enrichmentService.enrichFields(dealId, enrichFields, 'moneythumb', 0.95) writes a parallel store with confidence scoring — Firestore-side only.

13. Gotchas / nuances #

1. Two write paths, different field sets. Webhook→orchestrator writes the production-final values + 3m/6m/all aggregates + average_monthly_revenue__final_. Poller writes only the _extracted family. If only _extracted values are populated, the webhook never fired (or syncResultsToHubSpot was not invoked).
2. moneythumb_nsf_count_3m and moneythumb_total_nsfs_3m are identical. Both sum(last_3.num_nsfs). Pick one consumer-side; the duplication is intentional for backwards-compat.
3. clearHubspotDeal does NOT blank the 3m/6m/all aggregates or balance fields. Only blanks revenue-statistics group + moneythumb_avg_true_credits_6m. If the new sync produces fewer rows, older 3m/6m/all values may persist as stale.
4. HubSpot rollup propagation lag. number_of_associated_mca_positions, number_of_uw_docs__moneythumb, and n3/n4_month_avg_true_revenue update asynchronously. A sync that just completed may show stale rollups for tens of seconds.
5. cobalt_funding_position is gap-fill only. UW manual values must never be overwritten by the derivation. Verified by regression test.
6. moneythumb_app_status regression guard. Intake-side handlers will not reset to Ready if the status is in App Created, Upload Started, Upload Complete, Results Synced, Results Refreshed, or Error.
7. average_monthly_revenue__final_ group is verified_info, not moneythumb. Intentional — the canonical UW input regardless of upstream source.
8. Historic enum values may differ. moneythumb_status_changelog may include older labels like Results Synced to HubSpot. Catalog updated; changelog stays historical.
9. number_of_uw_docs__moneythumb is missing from the cached property catalog but exists in the live portal. Run npm run hubspot:sync:properties to refresh.
10. MT prefixes owner names with "DBA " — the company-enrichment path strips it and title-cases (enrichCompanyFromMoneyThumb.js:56).
11. PDFs under 50 KB are silently rejected by MT. Pre-validate at upload — see playbook LESSONS #3.
12. _extracted properties are UW-editable. Each PATCH first reads metadata.locked and skips locked fields.

14. Open questions #

1. Who writes moneythumb_status_changelog? No in-repo PATCH found. Likely a HubSpot workflow appending each moneythumb_app_status change. Confirm with portal admin.
2. Who writes moneythumb_update_timestamp? No in-repo writer.
3. Who writes moneythumb_source? Cleared by clearHubspotDeal.js:71 but never set in code. Presumably a workflow inferring source from upload toggles.
4. Who writes moneythumb_report_pdf? String labeled "Moneythumb Report PDF" in catalog. Whether this stores a URL to the summary UW Document is unclear from code.
5. Who writes deal_checklist___moneythumb_mca_stats_complete / _revenue_stats_complete? Likely workflow-driven.
6. Should clearHubspotDeal also blank the 3m/6m/all aggregates and balance fields? Currently does not — gap if next sync produces fewer months.
7. Are _extracted and _synced versions ever expected to differ? In principle they should track unless UW edits the _extracted and locks it. No automated reconciliation report.

15. Reference quick-look #