Fat Agent Standard / Core Objects
v1.0PolicySnapshot
Represents the financial values, policy state, and performance information of an insurance Policy at a specific point in time.
PolicySnapshot MUST reference a Policy by policy_id. It records what the Policy was worth, its status, and how it was performing as of a date. Historical Snapshots MUST remain distinct.
Identity
One Policy MAY have unlimited PolicySnapshots. Multiple Snapshots MAY exist for the same Policy and as_of_date when they come from different sources. Historical Snapshots MUST NOT be overwritten when later values arrive.
| Field | Type | Required | Description |
|---|---|---|---|
policy_snapshot_id | string | Yes | Unique identifier for the PolicySnapshot |
| policy_id | string | Yes | Policy represented by this Snapshot |
as_of_date | string (date) | Yes | Date the Snapshot represents |
as_of_time | string (time) | No | Time represented by the Snapshot when intraday precision is available |
policy_status | enum | No | Policy status as of the Snapshot. Uses the same taxonomy as Policy status. Allowed: pending, active, pending_cancellation, cancelled, expired, non_renewed, lapsed, reinstated, suspended, terminated, matured, paid_up, claim_pending, claim_paid, other |
policy_status_description | string | Yes* | Custom value when policy_status is other. Required when policy_status is other. MUST NOT be set otherwise. |
Source
Source provenance is mandatory. Calculated, estimated, imported, or manually entered values MUST remain distinguishable from carrier-reported values.
| Field | Type | Required | Description |
|---|---|---|---|
source_type | enum | Yes | Origin of the Snapshot data Allowed: carrier, carrier_api, agent, policyholder, policy_statement, illustration, imported_data, third_party, calculated, other |
source_type_description | string | Yes* | Custom value when source_type is other. Required when source_type is other. MUST NOT be set otherwise. |
source_id | string | No | ID of the originating entity or system when available |
source_date | string (date) | Yes | Date the source supplied or reported the data |
source_reference | string | No | External reference, statement number, API transaction, or file reference |
Life Values
Life Values describe applicability for life insurance products. Fields are stored at the PolicySnapshot root. Only applicable values SHOULD be supplied.
| Field | Type | Required | Description |
|---|---|---|---|
cash_value | number | No | Cash value as of the Snapshot |
account_value | number | No | Policy account value |
surrender_value | number | No | Amount available upon surrender |
death_benefit | number | No | Death benefit as of the Snapshot |
loan_balance | number | No | Outstanding policy loan balance |
withdrawal_value | number | No | Amount currently available for withdrawal |
premium_paid_to_date | number | No | Cumulative premium paid through the Snapshot date |
Annuity Values
Annuity Values describe applicability for annuity contracts. Shared concepts use the same root field names as Life Values: surrender_value, death_benefit, withdrawal_value, and premium_paid_to_date. Do not create life_* or annuity_* duplicates. guaranteed_lifetime_income MUST NOT be inferred from income_base unless source_type is calculated.
| Field | Type | Required | Description |
|---|---|---|---|
contract_value | number | No | Current annuity contract value |
income_value | number | No | Current value used for income calculations when applicable |
income_base | number | No | Current income benefit base |
withdrawal_available | number | No | Amount currently available for withdrawal without exceeding applicable contract provisions |
guaranteed_lifetime_income | number | No | Carrier-reported guaranteed lifetime income amount as of the Snapshot |
Interest / Crediting
credited_interest is interest actually credited by the carrier. External index movement and estimated policy performance MUST remain separate and MUST NOT automatically become credited_interest.
| Field | Type | Required | Description |
|---|---|---|---|
credited_interest | number | No | Interest actually credited to the Policy for the applicable period |
credited_interest_rate | number | No | Rate actually credited to the Policy, as a percentage-point value |
declared_rate | number | No | Current carrier-declared interest rate when applicable, as a percentage-point value |
Index Allocations
index_allocations represents indexed strategies associated with the Policy. Index values track market performance. Crediting terms and credited_interest represent carrier terms and actual crediting. estimated_current_value MAY be calculated and MUST remain distinguishable through Source. Rates and percentages use percentage-point values: 8.25 means 8.25%.
| Field | Type | Required | Description |
|---|---|---|---|
allocation_id | string | Yes | Unique identifier for this indexed allocation |
index_name | string | Yes | Name of the index |
index_identifier | string | No | External index identifier, ticker, or reference when available |
strategy_name | string | No | Carrier strategy or allocation name |
allocation_percentage | number | No | Percentage of applicable policy value allocated to the strategy. 25 means 25%. |
index_start_value | number | No | Index value at the beginning of the applicable crediting period |
index_current_value | number | No | Most recently observed index value |
index_close_value | number | No | Official closing index value for the Snapshot date when available |
index_change | number | No | Numeric change from the applicable index starting value |
index_change_percentage | number | No | Percentage change from the applicable index starting value |
daily_change | number | No | Numeric index gain or loss for the Snapshot date |
daily_change_percentage | number | No | Percentage index gain or loss for the Snapshot date |
participation_rate | number | No | Participation rate applicable to the indexed strategy |
cap_rate | number | No | Maximum credited rate when applicable |
spread_rate | number | No | Spread deducted under the strategy when applicable |
declared_rate | number | No | Carrier-declared rate applicable to the allocation |
floor_rate | number | No | Minimum credited rate under the strategy when applicable |
credited_rate | number | No | Rate actually credited by the carrier |
allocation_value | number | No | Carrier-reported current value of the indexed allocation |
allocation_start_value | number | No | Value allocated at the beginning of the crediting period |
estimated_current_value | number | No | Estimated current allocation value based on available performance data |
credited_interest | number | No | Interest actually credited to this allocation |
crediting_method | enum | No | Carrier crediting methodology Allowed: annual_point_to_point, multi_year_point_to_point, monthly_point_to_point, monthly_sum, monthly_average, daily_average, fixed_interest, other |
crediting_method_description | string | Yes* | Custom value when crediting_method is other. Required when crediting_method is other. MUST NOT be set otherwise. |
crediting_period_start | string (date) | No | Beginning of the applicable crediting period |
crediting_period_end | string (date) | No | End of the applicable crediting period |
last_crediting_date | string (date) | No | Most recent date carrier interest was actually credited |
Currency
currency is required when any monetary financial value is supplied.
| Field | Type | Required | Description |
|---|---|---|---|
currency | string | No | ISO 4217 currency code applicable to monetary values. Required when any monetary financial value is supplied. |
External References
external_references maps the Snapshot to identifiers from carriers or other systems, such as valuation IDs, API transactions, statement IDs, or market-data references.
| Field | Type | Required | Description |
|---|---|---|---|
system | string | Yes | External system |
reference_id | string | Yes | Identifier in the external system |
reference_type | string | No | Type of reference |
Source Types
source_type identifies where Snapshot values originated. Calculated estimates MUST remain distinguishable from carrier-reported values.
| Line of Business | Allowed product_type |
|---|---|
carrier | Carrier-reported |
carrier_api | Carrier API valuation |
agent | Agent entered |
policyholder | Policyholder supplied |
policy_statement | Policy statement |
illustration | Illustration |
imported_data | Imported data |
third_party | Third party |
calculated | Calculated estimate |
other | Requires source_type_description |
Validation Rules
- policy_snapshot_id, policy_id, as_of_date, source_type, and source_date MUST be supplied.
- One Policy MAY have unlimited PolicySnapshots. Every PolicySnapshot MUST reference exactly one Policy.
- Historical PolicySnapshots SHOULD NOT be overwritten when newer values become available.
- Multiple Snapshots MAY exist for the same policy_id and as_of_date when their sources differ.
- When an enum value is other, the companion {field}_description field is required and MUST be a non-empty string. That companion field MUST NOT be set unless the enum value is other.
- policy_status, when supplied, MUST use the same taxonomy as Policy status.
- A Snapshot MAY contain incomplete values when the source does not provide every field.
- Life Values and Annuity Values describe applicability. Shared financial concepts use one canonical field name.
- guaranteed_lifetime_income MUST NOT be inferred from income_base unless the Snapshot source identifies it as calculated.
- currency MUST use ISO 4217 and is required when any monetary financial value is supplied.
- External index performance, estimated policy performance, and actual carrier crediting are separate concepts.
- Daily index movement MUST NOT automatically be treated as credited_interest.
- credited_interest represents actual credited interest when reported as such.
- estimated_current_value MAY represent a calculated value and MUST remain distinguishable through Source.
- Rates and percentages use percentage-point values: 8.25 means 8.25%. Do not convert these to decimal fractions.
- as_of_date and source_date MUST use ISO 8601 date format (YYYY-MM-DD). as_of_time, when supplied, MUST use ISO 8601 time format.
- Health insurance and group insurance MUST NOT appear on PolicySnapshot.