---
title: "Optimize the Social Security claiming age"
method: POST
path: "/v1/social-security"
tags: ["Social Security"]
---

# Optimize the Social Security claiming age

`POST /v1/social-security`

## Request

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

Given the Primary Insurance Amount (PIA, the monthly benefit at Full Retirement Age) and birth year, computes the benefit at each claiming age 62–70 (applying the SSA early-claim reductions and delayed-retirement credits) and the age that maximizes lifetime benefits to a chosen longevity, plus the 62-vs-70 breakeven age. Amounts are real (today's) dollars; discount_rate is a real rate and present values discount to age 62. Calculation engine output, not financial advice. Deterministic.

## Request body

- SocialSecurityRequest
  - `birth_year` integer, required: Sets the Full Retirement Age.
  - `pia_monthly` number, required: Primary Insurance Amount — the monthly benefit at Full Retirement Age.
  - `longevity_age` integer, required: Life expectancy used for lifetime totals.
  - `discount_rate` number: Real annual rate for present value (0 = undiscounted).
  - `claim_age` integer: Optional. Primary's actual claim age, used for the household and earnings-test math. 0/absent = FRA.
  - `annual_earnings` number: Optional. Annual earned income for the earnings test (benefits withheld while working before FRA).
  - `earnings_test_year` integer: Required when annual_earnings > 0. Selects the year-keyed exempt amounts (2025 or 2026).
  - `cola_rate` number: Optional annual COLA; grows benefits from the claim year (nominal projection). 0 = real-dollar default.
  - `survivor_claim_age` integer: Optional. Age the surviving spouse claims the survivor benefit; before the survivor's FRA it is reduced (max 28.5% at 60). 0/absent = FRA (no reduction). Requires a spouse.
  - `spouse` object: Optional. Adds a spousal/survivor household analysis.
    - `pia_monthly` number, required: Spouse's own PIA (0 if they never worked).
    - `birth_year` integer, required
    - `claim_age` integer: Spouse's claim age; 0/absent = FRA.
    - `divorced` boolean: Ex-spouse (married 10+ years): entitled to the spousal benefit on the ex's PIA; combined household income is then reported as 0.

## Response `200`

Claiming analysis

- SocialSecurityResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` SocialSecurityRequest
    - `birth_year` integer, required: Sets the Full Retirement Age.
    - `pia_monthly` number, required: Primary Insurance Amount — the monthly benefit at Full Retirement Age.
    - `longevity_age` integer, required: Life expectancy used for lifetime totals.
    - `discount_rate` number: Real annual rate for present value (0 = undiscounted).
    - `claim_age` integer: Optional. Primary's actual claim age, used for the household and earnings-test math. 0/absent = FRA.
    - `annual_earnings` number: Optional. Annual earned income for the earnings test (benefits withheld while working before FRA).
    - `earnings_test_year` integer: Required when annual_earnings > 0. Selects the year-keyed exempt amounts (2025 or 2026).
    - `cola_rate` number: Optional annual COLA; grows benefits from the claim year (nominal projection). 0 = real-dollar default.
    - `survivor_claim_age` integer: Optional. Age the surviving spouse claims the survivor benefit; before the survivor's FRA it is reduced (max 28.5% at 60). 0/absent = FRA (no reduction). Requires a spouse.
    - `spouse` object: Optional. Adds a spousal/survivor household analysis.
      - `pia_monthly` number, required: Spouse's own PIA (0 if they never worked).
      - `birth_year` integer, required
      - `claim_age` integer: Spouse's claim age; 0/absent = FRA.
      - `divorced` boolean: Ex-spouse (married 10+ years): entitled to the spousal benefit on the ex's PIA; combined household income is then reported as 0.
  - `result` object
    - `full_retirement_age` object
      - `years` integer
      - `months` integer
    - `options` object[]: One entry per claiming age 62–70.
      - `claim_age` integer
      - `monthly_benefit` number
      - `annual_benefit` number
      - `percent_of_pia` number: Benefit as a fraction of PIA (e.g. 0.70 at 62 for FRA 67).
      - `lifetime_benefit` number: Nominal sum to longevity.
      - `lifetime_benefit_pv` number: Present value discounted to age 62.
      - `earnings_test_withholding` number: Annual benefit withheld by the earnings test for under-FRA years (0 unless annual_earnings is set and this option claims before FRA).
      - `earnings_test_withholding_fra_year` number: Withholding in the calendar year FRA is reached ($1 per $3 over the higher exempt amount). Present only when earnings are set and this option claims before FRA.
      - `restored_monthly_at_fra` number: Monthly benefit after withheld months are credited back at FRA (the earnings test defers, not forfeits). Present only when something is withheld.
      - `months_restored` integer: Number of withheld months credited back at FRA.
    - `optimal_claim_age` integer: Maximizes lifetime present value.
    - `optimal_claim_age_undiscounted` integer: Maximizes nominal lifetime total.
    - `breakeven_age_62_vs_70` integer: Age at which claiming at 70 overtakes claiming at 62 cumulatively (0 if never by 120).
    - `household` object: Spousal & survivor analysis; present only when a spouse is supplied.
      - `primary_monthly` number: Primary's benefit at their claim age.
      - `spouse_own_monthly` number: Spouse's own retirement benefit.
      - `spouse_spousal_monthly` number: Spousal-benefit level (up to 50% of primary PIA, reduced for early claim).
      - `spouse_total_monthly` number: What the spouse receives: max(own, spousal).
      - `combined_monthly` number: Both benefits together (0 for a divorced ex-spouse — no shared household).
      - `survivor_monthly` number: Benefit the survivor keeps after the first death (the higher of the two), reduced if claimed before the survivor's FRA.
      - `divorced` boolean: Whether the spouse is a divorced ex-spouse (independent entitlement).
      - `survivor_reduction_factor` number: Multiplier applied for an early survivor claim (present only when survivor_claim_age is set).
      - `survivor_monthly_at_fra` number: Unreduced survivor benefit at the survivor's FRA (present only when survivor_claim_age is set).
  - `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)