Extracting Beneficiary Designations From a Life Insurance Policy

A beneficiary designation is a small table with a hard constraint on it: within each tier, the shares add to one hundred. Everything difficult about extracting one comes from the ways a document expresses a share without writing a number.

Two tiers that are checked separately

Designations are ordered. Primary beneficiaries take the proceeds; contingent beneficiaries — also called secondary — take only if no primary beneficiary survives. Some designations add a third tier below that.

The tier is the field that makes the arithmetic work, because each tier sums to 100% independently. Two primaries at 50% each and three contingents at 33/33/34 is a complete, valid designation, and a validator that sums all five rows gets 200 and reports a defect that does not exist. Equally, a flat list that loses the tier makes the designation unusable: the order is the entire meaning of the document.

Extract tier as an explicit ordinal, not as a label copied from the form. Carriers use “Primary”, “First”, “Class 1”, “A” and blank-means-primary, and a blank tier column with a populated one above it usually means continuation of the tier above rather than an unassigned row — which is a layout inference and should be recorded as one.

Four ways a share is written

• A percentage. The easy case. Watch for shares written as whole numbers without a sign and as decimals.
• A fraction. “One-third” or “1/3”, which is exact and whose decimal expansion is not.
• “Equally” or “in equal shares”. A rule, not a number. Three beneficiaries sharing equally do not have 33.33% each; they have a third each, and if one predeceases, the division is over the survivors.
• A distribution instruction. Per stirpes directs that a deceased beneficiary’s share passes down their line of descendants; per capita divides among surviving individuals at a level. These qualify how a share is distributed on a contingency and are not shares themselves.

The temptation is to normalise everything to a percentage at extraction time, and it is the wrong move. Converting “equally among three” to 33.33/33.33/33.34 invents a rounding rule the document did not state and destroys the survivorship behaviour. Represent the share as a discriminated value instead:

{
  "tier": 1,
  "beneficiary_name_as_written": "Jordan A. Sample",
  "relationship": "spouse",
  "share": { "type": "equal_share" },
  "distribution_qualifier": "per_stirpes",
  "verbatim": "Primary: Jordan A. Sample, spouse, equally, per stirpes"
}

A downstream consumer that needs a number can compute one from the count of rows in the tier, with the rule visible. A stored 33.33 cannot be un-rounded.

There is a fifth form that breaks the check entirely: a share stated as a fixed amount rather than a proportion. “$50,000 to the named trust, the balance equally to my surviving children” mixes an absolute figure with a residual clause, and no tier of it sums to anything until the death benefit is known — which itself depends on the face amount, any accelerated benefit already paid, outstanding policy loans and unpaid premium. So the tier does not fail the 100% check; it is outside the check’s domain. Give the share type an amount and a residual variant, and make the validator skip a tier containing either rather than reporting a defect. A tier with a residual beneficiary is complete by construction, and a tier with fixed amounts and no residual is a genuine gap worth flagging for the opposite reason: if the amounts do not exhaust the benefit, the document does not say where the remainder goes.

Beneficiaries are also not always people. A trust, an estate (“the Estate of the Insured”), a charity, a business entity under a buy-sell arrangement, or a minor with a custodian named alongside them all appear, and each needs a different set of identifying fields. A single name column forces a trust with a trustee and a trust date into a string. Model beneficiary_type as an enum and let the identifying fields vary with it.

The 100% check and what a failure means

Group the extracted rows by tier and sum the numeric shares within each — a cross-field amount rule whose expected total happens to be a constant. Work the cases:

tier 1:  60 + 40                 = 100   ok
tier 1:  50 + 50 + 25            = 125   defect or missed tier boundary
tier 1:  33.33 + 33.33 + 33.33   =  99.99  rounding, tolerance applies
tier 1:  60                      =  60   a row was missed
tier 2:  100                     = 100   ok, independent of tier 1

A sum of 99.99 from three thirds is rounding and a tolerance of a few hundredths absorbs it. A sum of 125 is either a genuine defect in the document — which occurs, and is one of the useful things this extraction finds — or, more often, a tier boundary that was missed, so a contingent row was counted as primary. Check the second explanation before reporting the first: if any tier sums to more than 100 and another sums to less, a boundary error is far likelier than two independent drafting mistakes.

A sum below 100 with no rounding explanation usually means a row was dropped, and rows get dropped at page breaks and continuation forms. Do not resolve it by scaling the remaining shares up. Report the shortfall with the extracted rows attached and let a human look at the document, which is the standard argument for a targeted review queue rather than a blanket confidence threshold — see per-field extraction confidence for why an arithmetic check beats a score here.

The latest form wins

The designation in the policy document is frequently not the operative one. Beneficiaries are changed by filing a change-of-beneficiary form with the carrier, and each form supersedes the last. A file therefore contains a policy plus a stack of forms, and the answer is a function of dates rather than of any single document.

Which makes two fields mandatory on every extracted designation: the form’s own date, and the carrier’s acknowledgement or received date where present. They differ, and which one controls is a carrier and policy question this page cannot answer — but an extraction that captures both lets somebody who can answer it do so, and one that captures neither does not. Record also whether a designation is marked irrevocable, since an irrevocable designation constrains what a later form can do.

Handling the data

These documents contain names, relationships, dates of birth, addresses and sometimes government identifiers, for people who are not your customer and never agreed to anything. That is a reason to be deliberate about what leaves your own infrastructure: redact or tokenise identifiers before a document reaches a third-party model where the extraction does not need them, keep the retention of the extracted rows shorter than the retention of the source file if you can, and make sure the contract with whoever processes the data actually covers it — the field-by-field version of that check is in extracting data processing terms.

Every example on this page is synthetic, and that is the right habit for test fixtures too. A golden file built from a real policy is a copy of somebody’s personal data sitting in a git repository forever; redaction before the fixture is written costs nothing and removes the problem entirely.