Pensions API Reference (Fields and Sorting)

This document summarizes key fields for pensions-related endpoints and the allowed sort fields for each list.

Models (key fields)

Pension
- file_no (string), version (string), plan_id (string), plan_name (string)
- title, first, last, birth, race, sex
- info, valu, accrued, vested_per, start_age
- cola, max_cola, withdrawal, pre_dr, post_dr, tax_rate
PensionSchedule
- id, file_no, version, vests_on (date), vests_at (number), frequency (string)
MarriageHistory
- id, file_no, version, spouse_name (string), notes (text)
- married_from (date), married_to (date), married_years (number)
- service_from (date), service_to (date), service_years (number)
- marital_percent (number)
DeathBenefit
- id, file_no, version
- beneficiary_name (string), benefit_type (string), notes (text)
- lump1, lump2, growth1, growth2, disc1, disc2 (numbers)
- created_at, updated_at (timestamps)
SeparationAgreement
- id, file_no, version, agreement_date (date), terms (text), notes (text)

Allowed sort fields

Schedules (GET /api/pensions/schedules)
- id, file_no, version, vests_on, vests_at
Marriages (GET /api/pensions/marriages)
- id, file_no, version, married_from, married_to, marital_percent, service_from, service_to
Death benefits (GET /api/pensions/death-benefits)
- id, file_no, version, lump1, lump2, growth1, growth2, disc1, disc2, created
Separations (GET /api/pensions/separations)
- id, file_no, version, agreement_date

Notes

All list endpoints support skip, limit, sort_by, sort_dir, and include_total.
Whitelisted fields only are accepted for sorting; unknown fields fall back to defaults.
Tokenized search semantics: AND across tokens, OR across listed fields. Matching is case-insensitive and trims simple punctuation.
Sorting behavior: for string columns, sorting is case-insensitive (performed on lowercased values) for stable ordering.
Basic tokenized search is available per endpoint:
- Schedules: version, frequency
- Marriages: version, spouse_name, notes
- Death benefits: version, beneficiary_name, benefit_type, notes
- Separations: version, terms, notes

Examples (curl)

Schedules with filters, sorting, include_total:

curl \
  "http://localhost:6920/api/pensions/schedules?file_no=F-1&version=02&vests_at_min=10&vests_at_max=50&sort_by=vests_on&sort_dir=asc&include_total=true"

Marriages with tokenized search and sorting:

curl \
  "http://localhost:6920/api/pensions/marriages?file_no=F-1&search=Gamma&sort_by=married_from&sort_dir=desc"

Death benefits with numeric ranges and sorting:

curl \
  "http://localhost:6920/api/pensions/death-benefits?file_no=F-1&lump1_min=150&lump1_max=250&growth1_min=1.5&growth1_max=2.5&disc1_min=0.55&disc1_max=0.65&sort_by=lump1&sort_dir=desc"

Separations with date range filter and sorting:

curl \
  "http://localhost:6920/api/pensions/separations?file_no=F-1&start=2024-01-01&end=2024-03-31&sort_by=agreement_date&sort_dir=asc"

Nested detail with independent paging/sorting per section:

curl \
  "http://localhost:6920/api/pensions/F-1/detail?s_sort_by=vests_on&s_limit=5&m_sort_by=married_from&d_sort_by=lump1&sep_sort_by=agreement_date"

Example responses (shapes)

Schedules as a plain list (default):

[
  {
    "id": 1,
    "file_no": "F-1",
    "version": "01",
    "vests_on": "2024-01-01",
    "vests_at": 10.0,
    "frequency": "Monthly"
  },
  {
    "id": 2,
    "file_no": "F-1",
    "version": "01",
    "vests_on": "2024-02-01",
    "vests_at": 20.0,
    "frequency": "Monthly"
  }
]

Schedules with include_total=true:

{
  "items": [
    {
      "id": 1,
      "file_no": "F-1",
      "version": "01",
      "vests_on": "2024-01-01",
      "vests_at": 10.0,
      "frequency": "Monthly"
    }
  ],
  "total": 12
}

Pension detail with nested lists (trimmed):

{
  "pension": {
    "id": 123,
    "file_no": "F-1",
    "version": "01",
    "plan_id": "PID1",
    "plan_name": "Plan A",
    "vested_per": 50.0,
    "tax_rate": 25.0
  },
  "schedules": { "items": [/* ... */], "total": 3 },
  "marriages": { "items": [/* ... */], "total": 1 },
  "death_benefits": { "items": [/* ... */], "total": 0 },
  "separations": { "items": [/* ... */], "total": 2 }
}

Sample Pension record (GET /api/pensions/{pension_id}):

{
  "id": 123,
  "file_no": "F-1",
  "version": "01",
  "plan_id": "PID1",
  "plan_name": "Plan A",
  "title": "Mr.",
  "first": "John",
  "last": "Doe",
  "birth": "1970-05-01",
  "race": "W",
  "sex": "M",
  "info": "Notes...",
  "valu": 100000.0,
  "accrued": 50000.0,
  "vested_per": 50.0,
  "start_age": 65,
  "cola": 2.0,
  "max_cola": 3.0,
  "withdrawal": "ANNUITY",
  "pre_dr": 4.0,
  "post_dr": 3.0,
  "tax_rate": 25.0
}

4.8 KiB Raw Blame History