---
title: "Create a household"
method: POST
path: "/api/v1/households"
tags: ["households"]
---

# Create a household

`POST /api/v1/households`

## Request

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

Validates the document (reject, never clamp) and stores it. With `importKey`, the create is idempotent: a retry that matches an existing row answers 200 with `action: "already-created"`.

## Request body

- CreateHouseholdRequest
  - `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.
  - `label` string, nullable: Truncated to 128 chars.
  - `advisorRef` string, nullable: "" is treated as absent. Truncated to 128 chars.
  - `importKey` string, nullable: Your own stable id; makes the create idempotent (a retry that matches answers 200 with the existing row).

## Response `200`

The importKey matched a row this org already created; that row is returned untouched.

- object
  - `ok` unknown, required
  - `action` 'already-created', required
  - `household` object, 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
    - `importKey` string, nullable, required

## Other responses

- `201`: Created.
- `400`: Malformed JSON, a body of the wrong shape, or a top-level field that fails its check.
- `401`: No key presented (Authorization: Bearer wk_… or X-Api-Key).
- `402`: Unrecognized or revoked API key.
- `403`: The key's role is below the operation's floor (viewer < developer < owner), the key predates organization support, or the plan lacks the feature. On a sandbox key, also: the cap of 5 active households on create and import, the cap of 1 active Lodestar mandate, and the white-label surfaces (tenant config, embed tokens) and narration or mapping drafts on Worthune's model (they run on your own: a model assigned at /api/v1/model-policy, or x-model-key), which the sandbox does not carry.
- `422`: The household document failed validation (every issue, with paths).
- `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)