---
title: "Sweep a book you send (nothing stored)"
method: POST
path: "/api/v1/book-scan"
tags: ["book-scan"]
---

# Sweep a book you send (nothing stored)

`POST /api/v1/book-scan`

## Request

- Base URL: `https://worthune.com`
- URL: `https://worthune.com/api/v1/book-scan`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Runs the opportunity sweep over up to 250 household documents (25 on a sandbox key), storing none of them. Any key works. Every household is validated before any is scanned; an advisorRef containing "@" is rejected. Expense labels are stripped.

## Request body

- object
  - `households` object[], required
    - `ref` string: Your own reference, echoed as the queue entry's label (default household-<n>).
    - `advisorRef` string: Opaque label; must not contain "@".
    - `household` Household, required: Household object model v0.2.0 (docs/household-schema-spec.md). Validation rejects, never clamps, and returns every issue with a path. Cross-field rules: ids are unique per collection; every ownerId references a member; exactly one primary member and at most one spouse (a spouse requires married_joint); costBasis only on taxable accounts; holdings fractions sum to 1; a socialSecurity block only on social_security streams; endYear never precedes startYear.
      - `schemaVersion` '0.2.0', required
      - `filingStatus` 'single' | 'married_joint', required: MFS and head-of-household are not modeled (the tax module approximates them with Single ceilings and discloses it).
      - `state` 'AL' | 'AK' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'FL' | 'GA' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY' | 'DC': Two-letter USPS code (or DC). Optional: without it the household gets federal-only tax treatment, stated in the response assumptions.
      - `members` Member[], required
        - `id` string, required: Unique within members.
        - `birthYear` integer, required
        - `relationship` 'primary' | 'spouse' | 'dependent', required
        - `sex` 'male' | 'female': Needed only for longevity-aware Monte Carlo (NCHS sex-specific life table) and for pension-election / claiming strategies; a run that needs it rejects (never guesses) when an adult member lacks it.
      - `accounts` Account[], required
        - `id` string, required: Unique within accounts.
        - `wrapper` 'taxable' | 'traditional' | 'roth' | 'hsa' | 'plan529' | 'cash' | 'annuity', required
        - `ownerId` string, required: Must reference an existing member id (joint taxable accounts: the primary member).
        - `balance` number, required
        - `holdings` Holdings: Asset-class fractions that must sum to 1 (tolerance 1e-9). Omitted means the account is projected as one blended asset.
          - `us_equity` number
          - `intl_equity` number
          - `bonds` number
          - `cash` number
          - `real_assets` number
          - `other` number
        - `costBasis` number: Taxable accounts only (rejected on any other wrapper): total cost basis for gains treatment.
      - `liabilities` Liability[], required
        - `id` string, required: Unique within liabilities.
        - `kind` 'mortgage' | 'auto' | 'student' | 'credit_card' | 'personal', required
        - `balance` number, required
        - `annualRate` number, required: Annual nominal rate as a fraction (0.065 = 6.5%).
        - `monthlyPayment` number, required
      - `incomes` IncomeStream[], required
        - `id` string, required: Unique within incomes.
        - `ownerId` string, required: Must reference an existing member id.
        - `kind` 'salary' | 'self_employment' | 'rental' | 'pension' | 'social_security', required
        - `annualAmount` number, required
        - `startYear` integer: Calendar year, inclusive. Omitted = already flowing.
        - `endYear` integer: Calendar year, inclusive; must not precede startYear. Omitted = lifelong.
        - `growthRate` number: Annual nominal growth as a fraction. Omitted = the run's defaultIncomeGrowth.
        - `socialSecurity` SocialSecurityBlock: Only on kind = social_security. When present the engine COMPUTES the benefit from the §215(a) formula (the ssa-pia model): annualAmount is ignored and startYear defaults to the year the owner reaches claimAge.
          - `aime` number, required: Average Indexed Monthly Earnings, USD/month.
          - `claimAge` integer, required: Whole-year claiming age.
          - `fullRetirementAge` 66 | 67, required
      - `expenses` ExpenseStream[], required
        - `id` string, required: Unique within expenses.
        - `kind` 'living' | 'goal', required
        - `label` string: The only free-text field in the schema. Stripped before computing on the keyless routes (/project, /book-scan) so no identity reaches the engine or the record hash.
        - `annualAmount` number, required
        - `startYear` integer
        - `endYear` integer: Must not precede startYear.
        - `inflationAdjusted` boolean, required: True: the amount is in today's dollars and rides the inflation assumption.
  - `assumptions` ProjectionAssumptions, required: Unknown keys are rejected — the accepted set is exactly: annualReturn, inflationRate, defaultIncomeGrowth, socialSecurityCola, returnsByWrapper.
    - `annualReturn` number, required: Nominal annual return applied to every account balance (one blended rate).
    - `inflationRate` number, required: Annual inflation applied to inflation-adjusted expense streams.
    - `defaultIncomeGrowth` number, required: Growth for income streams that carry no growthRate of their own.
    - `socialSecurityCola` number: COLA applied to COMPUTED social_security benefits from each benefit's start year. Defaults to inflationRate; pass 0 for a flat benefit.
    - `returnsByWrapper` object: Per-wrapper returns; unlisted wrappers keep the blended annualReturn.
      - `taxable` number: Return for taxable accounts, replacing annualReturn (and any sampled path) for that wrapper.
      - `traditional` number: Return for traditional accounts, replacing annualReturn (and any sampled path) for that wrapper.
      - `roth` number: Return for roth accounts, replacing annualReturn (and any sampled path) for that wrapper.
      - `hsa` number: Return for hsa accounts, replacing annualReturn (and any sampled path) for that wrapper.
      - `plan529` number: Return for plan529 accounts, replacing annualReturn (and any sampled path) for that wrapper.
      - `cash` number: Return for cash accounts, replacing annualReturn (and any sampled path) for that wrapper.
      - `annuity` number: Return for annuity accounts, replacing annualReturn (and any sampled path) for that wrapper.
  - `horizon` ProjectionHorizon, required
    - `startYear` integer, required: First projected calendar year, an integer in [1900, 2150] on every surface.
    - `years` integer, required: Number of years to project.

## Response `200`

The queue, per-advisor rollups, skips and notes.

- object
  - `ok` unknown, required
  - `storage` object, required
    - `stored` unknown, required
    - `note` string, required
  - `upgrade` object, required
    - `note` string, required
    - `pricing` string, required
  - `queue` BookScanOpportunity[], required: Ranked by opportunityUsd, desc.
    - `householdId` integer, required: On the keyless route: the 1-based position in the submitted households array.
    - `label` string, nullable
    - `advisorRef` string, nullable
    - `strategy` string, required
    - `alternativeId` string, required
    - `alternativeLabel` string, required
    - `opportunityUsd` number, required: Top alternative's endingNetWorthDelta vs its own baseline — a triage estimate.
    - `improvesRuin` boolean, required
    - `recordSha256` string, required
  - `advisorRollups` object[], required
    - `advisorRef` string, nullable, required
    - `households` integer, required
    - `opportunities` integer, required
    - `opportunityUsd` number, required
    - `topOpportunityUsd` number, required
    - `improvesRuin` integer, required
  - `skipped` object[], required
    - `householdId` integer, required
    - `strategy` string, required
    - `reason` string, required
  - `householdsScanned` integer, required
  - `householdsTruncated` integer, required: Households beyond the cap that were NOT scanned — never silent.
  - `strategiesRun` string[], required
  - `notes` string[], required

## Other responses

- `400`: Malformed JSON, an empty or oversized households array, or bad assumptions/horizon.
- `401`: No key presented (Authorization: Bearer wk_… or X-Api-Key).
- `402`: Unrecognized or revoked API key.
- `403`: The key predates organization support (contact support for a free rotation).
- `422`: One or more households failed validation (paths are households[i].household.…), an advisorRef looked like an email, or the scan failed.
- `429`: Hourly per-org stateful quota, a per-route durable limit, or the 120 requests/minute per-IP burst backstop.
- `503`: Billing is not configured on this deployment; household resources are disabled rather than served without tenancy (production fail-closed).

---

[API](https://skmtc.dev/worthune/apis/worthune-api.md) · [All operations](https://skmtc.dev/worthune/apis/worthune-api/llms.txt) · [OpenAPI document](https://skmtc.dev/worthune/apis/worthune-api/revisions/9f2241072555?raw)