---
title: "Couple / household Social Security claiming optimizer"
method: POST
path: "/v1/social-security/couple-claim"
tags: ["Social Security"]
---

# Couple / household Social Security claiming optimizer

`POST /v1/social-security/couple-claim`

## Request

- Base URL: `https://api.numeratica.com`
- URL: `https://api.numeratica.com/v1/social-security/couple-claim`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Finds the claiming ages for a married couple that maximize the household's expected present value, accounting for spousal benefits while both are alive and the survivor benefit the surviving spouse keeps for life. A composite of the SSA mortality table and the single-person reduction / delayed-retirement-credit factors (no new data). Returns the optimal (claim_age_a, claim_age_b), the full expected-PV surface for a heatmap, and the gain over both-at-FRA / both-at-70 — so the canonical result is explicit: the higher earner usually delays (the survivor benefit), the lower earner can claim earlier. Benefits are real (today's) dollars; discount_rate is real. Deterministic; not advice.

## Request body

- CoupleClaimRequest
  - `spouse_a` ClaimSpouse, required
    - `pia_monthly` number: Monthly Primary Insurance Amount at Full Retirement Age (0 = never worked; spousal/survivor only).
    - `birth_year` integer, required: Determines Full Retirement Age.
    - `current_age` integer, required: Drives mortality and the earliest claimable age (<= 70).
    - `sex` 'male' | 'female', required: Mortality table.
    - `health_adjustment` number: Mortality scale: 1 = table, <1 healthier (longer), >1 frailer.
  - `spouse_b` ClaimSpouse, required
    - `pia_monthly` number: Monthly Primary Insurance Amount at Full Retirement Age (0 = never worked; spousal/survivor only).
    - `birth_year` integer, required: Determines Full Retirement Age.
    - `current_age` integer, required: Drives mortality and the earliest claimable age (<= 70).
    - `sex` 'male' | 'female', required: Mortality table.
    - `health_adjustment` number: Mortality scale: 1 = table, <1 healthier (longer), >1 frailer.
  - `discount_rate` number: Real annual discount rate for the present value (benefits are real dollars; 0 = undiscounted).

## Response `200`

The optimal claim ages + the expected-PV surface

- CoupleClaimResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` CoupleClaimRequest
    - `spouse_a` ClaimSpouse, required
      - `pia_monthly` number: Monthly Primary Insurance Amount at Full Retirement Age (0 = never worked; spousal/survivor only).
      - `birth_year` integer, required: Determines Full Retirement Age.
      - `current_age` integer, required: Drives mortality and the earliest claimable age (<= 70).
      - `sex` 'male' | 'female', required: Mortality table.
      - `health_adjustment` number: Mortality scale: 1 = table, <1 healthier (longer), >1 frailer.
    - `spouse_b` ClaimSpouse, required
      - `pia_monthly` number: Monthly Primary Insurance Amount at Full Retirement Age (0 = never worked; spousal/survivor only).
      - `birth_year` integer, required: Determines Full Retirement Age.
      - `current_age` integer, required: Drives mortality and the earliest claimable age (<= 70).
      - `sex` 'male' | 'female', required: Mortality table.
      - `health_adjustment` number: Mortality scale: 1 = table, <1 healthier (longer), >1 frailer.
    - `discount_rate` number: Real annual discount rate for the present value (benefits are real dollars; 0 = undiscounted).
  - `result` object
    - `optimal` object: The claim-age pair maximizing expected household PV.
      - `label` string
      - `claim_age_a` integer
      - `claim_age_b` integer
      - `expected_pv` number
    - `comparisons` object[]: Reference strategies (both_earliest, both_fra, both_70) and their expected PV.
      - `label` string
      - `claim_age_a` integer
      - `claim_age_b` integer
      - `expected_pv` number
    - `surface` object[]: The full expected-PV grid (one cell per claim-age pair) — for a heatmap.
      - `claim_age_a` integer
      - `claim_age_b` integer
      - `expected_pv` number
    - `fra_year_a` integer: Spouse A's Full Retirement Age (whole years).
    - `fra_year_b` integer: Spouse B's Full Retirement Age (whole years).
    - `gain_vs_latest` number: Optimal PV minus both-claim-at-70 PV.
    - `gain_vs_fra` number: Optimal PV minus both-claim-at-FRA PV.
  - `disclaimer` string

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key.
- `405`: Method not allowed
- `429`: The key's per-minute request budget is exceeded. Retry after the delay in the Retry-After header.
- `503`: A dependency (e.g. the key store) is temporarily unavailable, or the request exceeded its compute deadline. Retryable.

---

[API](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api.md) · [All operations](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/revisions/075bcfbd1ebf?raw)