---
title: "Compare a lump-sum pension offer to the monthly annuity"
method: POST
path: "/v1/pension/lump-sum-vs-annuity"
tags: ["Retirement income"]
---

# Compare a lump-sum pension offer to the monthly annuity

`POST /v1/pension/lump-sum-vs-annuity`

## Request

- Base URL: `https://api.numeratica.com`
- URL: `https://api.numeratica.com/v1/pension/lump-sum-vs-annuity`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Values the (optionally COLA-adjusted, optionally joint-and-survivor) pension stream at a discount rate, computes the implied return of taking the annuity versus the lump sum, and finds the nominal breakeven age. Reuses the npv-irr engine for the PV and internal-rate math. The longevity assumption is an input. Deterministic.

## Request body

- PensionRequest
  - `current_age` integer, required
  - `lump_sum_offer` number, required
  - `monthly_pension` number, required
  - `cola_rate` number: Annual pension increase.
  - `discount_rate` number, required
  - `end_age` integer, required: Primary longevity assumption.
  - `survivor_pct` number: Joint-and-survivor: fraction continued after end_age.
  - `survivor_end_age` integer: Survivor longevity (>= end_age).

## Response `200`

Comparison

- PensionResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` PensionRequest
    - `current_age` integer, required
    - `lump_sum_offer` number, required
    - `monthly_pension` number, required
    - `cola_rate` number: Annual pension increase.
    - `discount_rate` number, required
    - `end_age` integer, required: Primary longevity assumption.
    - `survivor_pct` number: Joint-and-survivor: fraction continued after end_age.
    - `survivor_end_age` integer: Survivor longevity (>= end_age).
  - `result` object
    - `pension_present_value` number: PV of the pension stream at discount_rate.
    - `lump_sum_offer` number
    - `net_advantage_annuity` number: PV(pension) - lump (>0 favors the annuity).
    - `recommendation` 'annuity' | 'lump_sum'
    - `implied_return` number: Discount rate at which the two are equal (omitted if none).
    - `breakeven_age` integer: Age cumulative nominal pension overtakes the lump (0 if never).
  - `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)