DIYMF API Documentation Snapshot

Overview

This API is designed around verified financial state

DIYMF does not treat personal finance as a generic retrieval problem. Institutions provide baseline profile facts, domain inputs, and optional source documents. The platform normalizes those inputs into a Financial State Model, computes domain-level KPIs, and only then uses bounded reasoning to explain the result.

Inputs

Profile facts, KPIs, and documents

State

Canonical Financial State Model per user

Compute

Deterministic KPI engines by domain

Answer

Grounded explanation plus evidence metadata

Integration Flow

Identify the user with a stable externalUserId unique within your organization and tenant context.

Send baseline Financial State Model profile facts to /api/hre/users/profile so the platform has authoritative cross-domain context.

Submit authoritative KPIs through /api/hre/kpis and optionally upload supporting documents through /api/hre/ingest for extraction and evidence grounding.

Call /api/hre/ask once profile and at least one domain input exists. The platform computes the decision state first, then explains it.

Track asynchronous ingest jobs through /api/hre/ingest/status/:docId and store returned document identifiers for later audit and lifecycle operations.

Core Endpoints

POST/api/hre/users/profile

Create or update the canonical Financial State Model profile for a user.

Request shape

{
  "externalUserId": "user_123",
  "profile": {
    "age": 42,
    "retirementAge": 65,
    "incomeAnnualGross": 165000,
    "incomePostTax": 108500,
    "householdSize": 3,
    "filingStatus": "married_filing_jointly",
    "state": "CA",
    "totalDebt": 240000,
    "retirementSavingsTotal": 310000,
    "riskTolerance": "moderate"
  }
}

Profile facts are authoritative baseline inputs and do not need to be resent on every ask request.
Use stable financial facts here rather than transient scenario assumptions.

POST/api/hre/kpis

Submit domain KPIs your systems already compute so DIYMF can use them as verified facts.

Request shape

{
  "externalUserId": "user_123",
  "domain": "budget",
  "metrics": {
    "monthlyExpensesTotal": 11854,
    "budgetCategories": {
      "housing": 3200,
      "food": 1329,
      "transportation": 518
    }
  }
}

Partner-supplied KPIs override platform-computed values when both exist.
Use canonical domain field names to preserve explainability and peer comparison behavior.

POST/api/hre/ingest

Upload documents for extraction, evidence references, and grounded explanation support.

Request shape

form-data:
externalUserId=user_123
domain=tax
docType=irs_1040
file=@/path/to/1040.pdf

Use multipart/form-data for file uploads.
Upload documents when you want evidence-grounded explanations or extraction of missing fields.

GET/api/hre/ingest/status/:docId

Track asynchronous processing state for a previously uploaded document.

Request shape

GET /api/hre/ingest/status/doc_123

Persist docId values returned by ingest.
Polling is appropriate for async extraction flows; processed docs can then influence ask responses.

POST/api/hre/ask

Request a bounded explanation grounded in user state, KPIs, and evidence references.

Request shape

{
  "externalUserId": "user_123",
  "domain": "retirement",
  "question": "Am I on track for retirement?"
}

Ask is not intended to invent financial truth; it explains computed state and attached evidence.
If required inputs are missing, the system can return a missing-input response instead of bluffing.

Response Codes

200

Success. Profile, KPI, or answer returned.

202

Accepted for asynchronous processing, typically document ingest.

400

Invalid payload, missing fields, or unsupported domain input.

401

Missing or invalid API key.

403

Policy, licensing, or environment restrictions prevent the action.

429

Rate limit exceeded.

500

Server-side error.

FSM Profile

Baseline cross-domain profile fields

The Financial State Model is the canonical baseline state for a user. These are representative fields used across multiple domains before domain-specific KPIs are added.

Field	Type	Notes
`age`	number	Current age of the user.
`retirementAge`	number	Target retirement age used by retirement projections.
`incomeAnnualGross`	number	Annual gross income before deductions.
`incomePostTax`	number	Annual or normalized post-tax take-home income.
`monthlyExpensesTotal`	number	Current monthly spending baseline.
`householdSize`	number	Household context used across planning domains.
`filingStatus`	string	Tax filing status, such as single or married_filing_jointly.
`state`	string	US state used for tax and cost assumptions.
`totalDebt`	number	Aggregate debt outstanding across tracked obligations.
`retirementSavingsTotal`	number	Current retirement account balance total.
`riskTolerance`	string	Risk posture used for allocation alignment analysis.

Domain Slices

Required inputs and computed outputs by domain

Budget

Cash-flow planning, spend diagnostics, and budget pressure analysis.

Required inputs

incomePostTax
monthlyExpensesTotal
budgetCategories

Optional inputs

peerGroup
monthlySavingsTarget
recurringBills

Computed outputs

savingsRate
freeToSpend
discretionarySpendShare
budgetGap
peerSpendDelta

Tax

Estimated tax position, deduction coverage, withholding gap, and scenario deltas.

Required inputs

filingStatus
incomeAnnualGross
state
taxYear

Optional inputs

federalWithholding
itemizedDeductions
childDependents

Computed outputs

estimatedTax
effectiveTaxRate
withholdingGap
deductionDelta
creditCoverage

Retirement

Readiness analysis, nest-egg projections, income gap, and longevity modeling.

Required inputs

age
retirementAge
retirementSavingsTotal
annualContribution

Optional inputs

expectedReturn
desiredRetirementIncome
socialSecurityEstimate

Computed outputs

projectedNestEgg
incomeGap
safeWithdrawalIncome
longevityYears
goalShortfall

Debt

Debt prioritization, payoff horizon, and interest reduction scenarios.

Required inputs

totalDebt
interestRates
minimumPayments
monthlyFreeCashFlow

Optional inputs

promoExpiryDates
securedDebtMix

Computed outputs

payoffOrder
payoffHorizon
interestSaved
paymentStressScore

Policy-aware guidance

Policy-aware guidance is a governed runtime layer, not a prompt hack

DIYMF applies policy-aware guidance as controlled runtime configuration. This layer can narrow an answer, add conditions, route a workflow, flag missing facts, or alter how the system interprets the same user state. It does not change the endpoint names, but it can change how an answer is evaluated and explained.

Platform policy-aware guidance

Baseline policy-aware guidance maintained by DIYMF for supported domains and evaluator families.

Institution policy-aware guidance

Client-specific overlays for internal policy, review thresholds, disclosures, routing, and preferred treatment.

Runtime activation

Policy-aware guidance is applied from active org and domain configuration; it is not a casual prompt toggle on the public API.

What platform policy-aware guidance covers

Domain-level policy interpretation for supported finance workflows such as budget, tax, debt, retirement, and investment analysis.
Threshold and routing logic for when an answer should stay conditional, request more facts, or trigger manual review.
Runtime controls for privacy posture, trace detail, and evidence usage so explanations stay within approved bounds.
Policy-aware explanation rules that shape how deterministic outcomes are phrased, limited, and disclosed to end users.

Current platform rule packs

The current reviewed public baseline contains 10 approved platform rule packs. These are the concrete policy-aware rule packs behind the runtime layer today.

10 approved

Section 1033 final rule

open_banking.1033.final_rule.us.2024.v1

Core personal financial data rights scope and role-based obligations under CFPB Section 1033.

Section 1033 compliance timing

open_banking.1033.compliance_timing.us.2025.v1

Timing and status logic covering the final rule, reconsideration track, and stayed compliance dates.

Section 1033 third-party obligations

open_banking.1033.third_party_obligations.us.2024.v1

Authorized third-party and intermediary obligations tied to consent scope, data use, and revocation handling.

1033 transaction-data access for budgeting and payments

budget_payments.1033.transaction_data_access.us.2024.v1

Applies Section 1033 access and consent obligations to budgeting and payments workflows using transaction data.

SR 11-7 model risk management

institutional_risk.sr_11_7.model_risk.us.v1

Governance, validation, monitoring, and effective challenge expectations for material model-driven decisions.

SR 21-8 BSA/AML model risk

institutional_risk.sr_21_8.bsa_aml_model_risk.us.v1

Model risk expectations for bank systems supporting BSA/AML workflows and related governance controls.

FinCEN BOI 2025 change

general_finance.fincen_boi.change_2025.us.v1

Captures the 2025 BOI reporting change affecting U.S. companies, U.S. persons, and certain foreign entities.

OBBBA consumer tax changes

general_finance.obbba.consumer_tax_changes.us.2025.v1

Current-law tax change pack for OBBBA-driven consumer tax guidance and downstream decision logic.

2026 IRA and Roth phaseouts

investments.ira_roth_phaseouts.us.2026.v1

Contribution eligibility and phaseout treatment based on filing status, MAGI, age, and account type.

2026 RMD timing

investments.rmd_timing.us.2026.v1

Required minimum distribution timing by age, account type, beneficiary status, and Roth-owner treatment.

Runtime effects

Policy-aware guidance may narrow the answer or force conditional language.
Policy-aware guidance may add missing-fact requests rather than allowing a definitive answer.
Policy-aware guidance may route the evaluation through threshold, scope, timing, or checklist logic.
Where trace settings allow it, compliance exports can show which policy-aware guidance path influenced the output.

Evaluator family	Typical use
Threshold	Numeric cutoffs such as high-balance review, tolerance checks, or compliance gates.
Scope / routing	Role-product scope, subtopic routing, and deciding which policy family applies.
Timing / lifecycle	Policy-aware logic that changes by implementation stage, review period, or effective date window.
Checklist / control gap	Model risk, governance, and operational-control assessments where missing controls matter.

Compliance Model

Audit-ready exports are part of the product surface

The compliance export is intentionally scrubbed. It is designed so a compliance officer can answer: what happened, what data was relied on, under what policy, and whether the decision path can be reproduced without exposing raw prompts or turning the platform into a raw-document vault.

Envelope field	Meaning
`status`	Request status for report generation.
`requestId`	Unique report generation identifier.
`reportVersion`	Schema version for the compliance report payload.
`generatedAt`	Timestamp when the report was generated.
`orgId`	Organization identifier the report is scoped to.
`from / to`	Inclusive reporting window for the exported report.

Summary

enabledDomains: domains enabled for the org at report time
retentionDays: retention policy for docs, logs, and embeddings
environment: deployment mode for the org

Privacy and scrub controls

piiScrubbingEnabled: whether redaction/scrubbing is active
piiScrubProvider: provider or pipeline used for scrubbing
retention windows: docs, logs, embeddings, and optional scrubbed text

Trace identifiers

traceId: end-to-end trace identifier
questionHash: SHA-256 hash of the original question
answerHash: SHA-256 hash of the final answer

Policy and constraints

kpiPolicy, docAiPolicy, taxMappingPolicy, and traceLevel applied at runtime
policy metadata showing whether PII scrubbing was active
runtime constraints that shaped the answer path

Evidence and execution

docRefs and embeddingRefs used for grounded evidence
enginePath, KPI source, retrieval quality, and model provider
answer metadata that supports replayability and audit review

Trace detail levels

summary

Includes

High-level outcome and policy metadata.

Excludes

Evidence arrays and snippet previews.

metadata

Includes

Trace metadata and evidence references such as ids and scores.

Excludes

Snippet previews.

scrubbed_preview

Includes

Metadata plus short scrubbed snippet previews.

Excludes

Raw document text and raw prompts.

Runtime Model

Example grounded response

Answers are intended to expose the computed state and evidence metadata, not replace deterministic financial truth with unconstrained language.

{
  "status": "ok",
  "domain": "retirement",
  "answer": "Your current retirement plan is close to target but still shows a projected income gap.",
  "kpis": {
    "projectedNestEgg": 2935276,
    "incomeGap": 40611,
    "safeWithdrawalIncome": 117411,
    "longevityYears": 30
  },
  "trace": {
    "traceLevel": "scrubbed_preview",
    "evidence": [
      { "id": "doc_1040_2025", "score": 0.91 },
      { "id": "profile_state_v12", "score": 1.0 }
    ]
  }
}

This public page is a documentation snapshot, not a substitute for contractual onboarding, environment-specific credentials, or tenant configuration. It exists so institutional evaluators can inspect the real shape of the platform before entering the portal workflow.

Decision Intelligence API Reference

This API is designed around verified financial state

Baseline cross-domain profile fields

Required inputs and computed outputs by domain

Policy-aware guidance is a governed runtime layer, not a prompt hack

Audit-ready exports are part of the product surface

Example grounded response