---
title: "Get a household (with document)"
method: GET
path: "/api/v1/households/{id}"
tags: ["households"]
---

# Get a household (with document)

`GET /api/v1/households/{id}`

## Request

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

## Response `200`

The row and its document (archived rows stay readable).

- object
  - `ok` unknown, required
  - `household` HouseholdResource, required
    - `id` integer, required
    - `label` string, nullable, required
    - `advisorRef` string, nullable, required
    - `schemaVersion` string, required
    - `version` integer, required: Monotonic write counter for optimistic concurrency.
    - `status` 'active' | 'archived', required
    - `lastComputedAt` string, date-time, nullable, required
    - `doc` 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.

## Other responses

- `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).
- `404`: No household with this id in the key's organization (PUT, PATCH, POST project and POST decisions also answer 404 for archived rows; GET, the decision list and the picture still serve them).
- `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)