Retirement income

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

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.

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

Request body

premiumnumber

0 = solve from target_income.

target_incomenumber

Annual; 0 = solve from premium.

ageinteger required
sex'male' | 'female' required
assumed_ratenumber required

Pricing interest rate.

start_ageinteger

Defer payments to this age (QLAC); 0/absent = immediate.

payout_type'life' | 'period_certain' | 'joint_survivor' required
period_certain_yearsinteger

Guaranteed years (period_certain).

survivor_pctnumber

Fraction the survivor receives (joint_survivor).

second_ageinteger
second_sex'male' | 'female'

Example request

{
  "premium": 100000,
  "age": 65,
  "sex": "male",
  "assumed_rate": 0.045,
  "payout_type": "life"
}

Response

Annuity pricing

result_idstring
engine_versionstring
disclaimerstring

Example response

{
  "result_id": "ann_1a2b3c4d5e6f7a8b",
  "engine_version": "annuity-1.0.0",
  "inputs": {
    "premium": 100000,
    "age": 65,
    "sex": "male",
    "assumed_rate": 0.045,
    "payout_type": "life"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.