---
title: "Price an income annuity (SPIA / QLAC) on the mortality table"
method: POST
path: "/v1/annuity"
tags: ["Retirement income"]
---

# Price an income annuity (SPIA / QLAC) on the mortality table

`POST /v1/annuity`

## Request

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

Given a premium, solves the annual/monthly income the annuity buys (or, given a target income, the premium required), with the expected total payout and a money's-worth ratio. Supports immediate or deferred (QLAC start_age), and life / period-certain / joint-and-survivor payouts. Priced as the survival-weighted present value on the SSA 2021 mortality table at the assumed rate. Deterministic; not an insurance quote.

## Request body

- AnnuityRequest: Provide a premium, a target_income, or both (both evaluates a quote's money's-worth).
  - `premium` number: 0 = solve from target_income.
  - `target_income` number: Annual; 0 = solve from premium.
  - `age` integer, required
  - `sex` 'male' | 'female', required
  - `assumed_rate` number, required: Pricing interest rate.
  - `start_age` integer: Defer payments to this age (QLAC); 0/absent = immediate.
  - `payout_type` 'life' | 'period_certain' | 'joint_survivor', required
  - `period_certain_years` integer: Guaranteed years (period_certain).
  - `survivor_pct` number: Fraction the survivor receives (joint_survivor).
  - `second_age` integer
  - `second_sex` 'male' | 'female'

## Response `200`

Annuity pricing

- AnnuityResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` AnnuityRequest: Provide a premium, a target_income, or both (both evaluates a quote's money's-worth).
    - `premium` number: 0 = solve from target_income.
    - `target_income` number: Annual; 0 = solve from premium.
    - `age` integer, required
    - `sex` 'male' | 'female', required
    - `assumed_rate` number, required: Pricing interest rate.
    - `start_age` integer: Defer payments to this age (QLAC); 0/absent = immediate.
    - `payout_type` 'life' | 'period_certain' | 'joint_survivor', required
    - `period_certain_years` integer: Guaranteed years (period_certain).
    - `survivor_pct` number: Fraction the survivor receives (joint_survivor).
    - `second_age` integer
    - `second_sex` 'male' | 'female'
  - `result` object
    - `annual_income` number
    - `monthly_income` number
    - `premium` number
    - `apv_factor` number: Actuarial PV of $1/yr of income.
    - `expected_payout` number: Expected total nominal income over the annuitant's life.
    - `moneys_worth` number: PV(benefits)/premium; 1.0 = actuarially fair at the assumed rate.
  - `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)