Fat Agent Standard / Core Objects

v1.0

Policy

Represents one issued insurance contract and one policy number.

Policy MUST reference other Fat Agent Standard objects rather than duplicate their underlying data.

Identity

Field	Type	Required	Description
`policy_id`	string	Yes	Unique identifier for the Policy
`policy_number`	string	Yes	Carrier-assigned policy or contract number
`status`	enum	Yes	Current status of the Policy Allowed: pending, active, pending_cancellation, cancelled, expired, non_renewed, lapsed, reinstated, suspended, terminated, matured, paid_up, claim_pending, claim_paid, other
`status_description`	string	Yes*	Custom value when status is other. Required when status is other. MUST NOT be set otherwise.
`issue_date`	string (date)	No	Date the carrier issued the Policy
`effective_date`	string (date)	No	Date coverage becomes effective
`expiration_date`	string (date)	No	End date of the current policy term
`renewal_date`	string (date)	No	Date the Policy is scheduled to renew
`termination_date`	string (date)	No	Date coverage terminated when applicable

Carrier / Product

A Policy represents one issued insurance product. The same Fat Agent Standard line-of-business and product-type taxonomy used by Quote and Application MUST be used by Policy. Health insurance and group insurance are outside the scope of Fat Agent Standard v1.0.

Field	Type	Required	Description
carrier_id	string	Yes	ID of the issuing Carrier
product_id	string	No	ID of the carrier Product
`line_of_business`	enum	Yes	Broad insurance line Allowed: life, annuity, long_term_care, disability, personal_auto, property, personal_umbrella, commercial, other
`line_of_business_description`	string	Yes*	Custom value when line_of_business is other. Required when line_of_business is other. MUST NOT be set otherwise.
`product_type`	string	Yes	Standardized product classification within the line of business. MUST be valid for the selected line_of_business.
`product_type_description`	string	Yes*	Custom value when product_type is other. Required when product_type is other. MUST NOT be set otherwise.

Source

Source maintains traceability through Quote → Application → Policy. A Policy MAY exist without a Quote or Application reference when imported from an external system. One Application MAY be referenced by multiple Policy objects.

Field	Type	Required	Description
application_id	string	No	Application that resulted in this Policy
`quote_id`	string	No	Quote associated with the Policy

Parties

parties connects Person or Organization objects to the Policy. Each party MUST contain person_id OR organization_id, but MUST NOT contain both. Driver numbering such as Driver 1 MUST NOT be used. Primary and contingent beneficiaries MUST be separate roles. The parties array allows an unlimited number of drivers.

Field	Type	Required	Description
person_id	string	No	ID of related Person. Required when organization_id is not supplied.
organization_id	string	No	ID of related Organization. Required when person_id is not supplied.
`role`	enum	Yes	Party's role on the Policy Allowed: insured, named_insured, additional_insured, owner, payer, primary_beneficiary, contingent_beneficiary, annuitant, joint_insured, driver, mortgagee, lienholder, loss_payee, authorized_signer, other
`role_description`	string	Yes*	Custom value when role is other. Required when role is other. MUST NOT be set otherwise.
`driver_type`	enum	No	Driver classification when role is driver Allowed: primary, additional, excluded, other
`driver_type_description`	string	Yes*	Custom value when driver_type is other. Required when driver_type is other. MUST NOT be set otherwise.

Coverages

coverages references Coverage objects associated with the Policy. Limits, deductibles, riders, benefits, and coverage-specific terms belong in the Coverage object.

Field	Type	Required	Description
coverage_id	string	Yes	ID of related Coverage

Risks

risks references insured risk objects. Examples: Life Policy → Person; Auto Policy → Vehicle; Homeowners Policy → Property; Commercial Policy → Organization and/or Property.

Field Type Required Description

Field	Type	Required	Description
`risk_id`	string	Yes	ID of the insured risk
`risk_type`	enum	Yes	Type of Standard object being referenced Allowed: person, organization, vehicle, property, other
`risk_type_description`	string	Yes*	Custom value when risk_type is other. Required when risk_type is other. MUST NOT be set otherwise.

risk_id

string

Yes

ID of the insured risk

risk_type

enum

Yes

Type of Standard object being referenced

Allowed: person, organization, vehicle, property, other

risk_type_description

string

Yes*

Custom value when risk_type is other. Required when risk_type is other. MUST NOT be set otherwise.

Premium

premium contains contract-level premium information. currency SHOULD use ISO 4217 codes such as USD.

Field	Type	Required	Description
`premium_amount`	number	No	Premium amount for the selected payment frequency
`premium_frequency`	enum	No	Frequency at which premium is paid Allowed: monthly, quarterly, semiannual, annual, single_premium, other
`premium_frequency_description`	string	Yes*	Custom value when premium_frequency is other. Required when premium_frequency is other. MUST NOT be set otherwise.
`annual_premium`	number	No	Annualized premium
`currency`	string	No	ISO 4217 currency code

Billing

billing contains basic policy-level billing information. Detailed payment transactions MUST NOT be stored directly on Policy.

Field	Type	Required	Description
`billing_method`	enum	No	Method used to bill or collect premium Allowed: direct_bill, agency_bill, eft_ach, credit_debit_card, payroll_deduction, other
`billing_method_description`	string	Yes*	Custom value when billing_method is other. Required when billing_method is other. MUST NOT be set otherwise.
`billing_status`	enum	No	Current billing state Allowed: current, due, past_due, grace_period, paid, suspended, other
`billing_status_description`	string	Yes*	Custom value when billing_status is other. Required when billing_status is other. MUST NOT be set otherwise.
`next_due_date`	string (date)	No	Next scheduled premium due date

Producers

producers connects Producer and Agency objects to the Policy. Multiple producers MAY be associated with one Policy. The Standard MUST NOT assume only one writing agent exists. At least producer_id or agency_id MUST be supplied for each entry.

Field	Type	Required	Description
producer_id	string	No	ID of the Producer
agency_id	string	No	ID of the Agency
`role`	enum	Yes	Producer or distribution role Allowed: writing_agent, servicing_agent, broker, agency, imo, fmo, other
`role_description`	string	Yes*	Custom value when role is other. Required when role is other. MUST NOT be set otherwise.

Prior Policies

prior_policies references PriorPolicy objects. Prior-insurance and replacement information MUST NOT be duplicated inside Policy.

Field	Type	Required	Description
prior_policy_id	string	Yes	ID of related PriorPolicy

Underwriting

underwriting references Underwriting objects associated with the Policy. Underwriting information MUST NOT be duplicated inside Policy.

Field	Type	Required	Description
underwriting_id	string	Yes	ID of related Underwriting object

Endorsements

endorsements references Endorsement objects that modify the Policy after issuance. Coverage represents protection provided by the Policy. Endorsement represents a change to the Policy. Those concepts MUST remain separate.

Field	Type	Required	Description
endorsement_id	string	Yes	ID of related Endorsement

Policy Values / Snapshots

Changing financial values MUST NOT be stored as static fields on Policy. Life and annuity values that change over time belong on PolicySnapshot. Every PolicySnapshot MUST include as_of_date, source_type, and source_date.

Field	Type	Required	Description
policy_snapshot_id	string	Yes	ID of related PolicySnapshot

Documents

documents references Document/Evidence objects associated with the Policy. Actual document metadata and file information belong in Document/Evidence.

Field	Type	Required	Description
`document_id`	string	Yes	ID of related Document/Evidence object

Claims / Losses

claims_losses references Claim/Loss objects associated with the Policy. Claim details MUST NOT be duplicated inside Policy.

Field	Type	Required	Description
claim_loss_id	string	Yes	ID of related Claim/Loss object

External References

external_references maps the Policy to identifiers in external systems, such as carrier policy administration IDs, AMS policy IDs, CRM IDs, billing system IDs, or third-party platform IDs.

Field	Type	Required	Description
`system`	string	Yes	External system or source
`reference_id`	string	Yes	Identifier assigned by that system
`reference_type`	string	No	Type of external reference

Line of Business and Product Types

product_type MUST be valid for the selected line_of_business. Health insurance and group insurance are outside Fat Agent Standard v1.0. When line_of_business is other, line_of_business_description MUST be supplied, product_type SHOULD be other, and product_type_description MUST describe the product.

Line of Business	Allowed product_type
`life`	term_life, whole_life, universal_life, indexed_universal_life, guaranteed_universal_life, final_expense, other
`annuity`	fixed_annuity, myga, fixed_indexed_annuity, spia, variable_annuity, other
`long_term_care`	traditional_ltc, hybrid_ltc, other
`disability`	short_term_disability, long_term_disability, other
`personal_auto`	standard_auto, non_standard_auto, classic_collectible_auto, motorcycle, recreational_vehicle, other
`property`	homeowners, condo, renters, dwelling_fire, mobile_manufactured_home, flood, other
`personal_umbrella`	personal_umbrella, other
`commercial`	businessowners, commercial_package, commercial_property, general_liability, commercial_auto, workers_compensation, commercial_umbrella, professional_liability, errors_omissions, directors_officers, employment_practices_liability, cyber, inland_marine, builders_risk, equipment_breakdown, crime, bonds, other
`other`	other

Validation Rules

One Policy object represents one issued insurance contract and one policy number.
policy_id, policy_number, status, carrier_id, line_of_business, and product_type MUST be supplied.
One Application MAY result in multiple Policy objects. Policy MUST NOT contain multiple unrelated issued contracts.
The lifecycle is Quote → Application → Policy. application_id and quote_id MAY be omitted when the Policy is imported from an external system.
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.
Every Product type MUST be valid for its selected line_of_business.
Health insurance and group insurance MUST NOT appear on Policy.
Every party MUST reference either a Person OR an Organization, but not both.
Driver numbering MUST NOT be used. Primary, additional, and excluded driver classification uses driver_type, and only when role is driver.
Primary and contingent beneficiaries MUST be represented as separate roles.
Multiple producers MAY be associated with one Policy. Every producer entry MUST contain at least producer_id or agency_id.
Policy MUST reference Coverage, risk objects, Underwriting, PriorPolicy, Endorsement, Claim/Loss, and PolicySnapshot rather than duplicating those schemas.
Changing financial values such as cash_value belong in PolicySnapshot rather than static Policy fields.
Detailed payment transactions MUST NOT be stored on Policy.
Dates MUST use ISO 8601 date format (YYYY-MM-DD).
currency SHOULD use ISO 4217 codes.
premium_amount and annual_premium MUST be greater than or equal to zero when supplied.

{
  "policy_id": "POL12345",
  "policy_number": "AUTO-987654321",
  "status": "active",
  "issue_date": "2026-09-20",
  "effective_date": "2026-10-01",
  "expiration_date": "2027-04-01",
  "renewal_date": "2027-04-01",
  "carrier_id": "CAR123",
  "product_id": "PROD456",
  "line_of_business": "personal_auto",
  "product_type": "standard_auto",
  "application_id": "APP12345",
  "quote_id": "QUOTE12345",
  "parties": [
    {
      "person_id": "P12345",
      "role": "named_insured"
    },
    {
      "person_id": "P12345",
      "role": "driver",
      "driver_type": "primary"
    },
    {
      "person_id": "P67890",
      "role": "driver",
      "driver_type": "additional"
    }
  ],
  "coverages": [
    {
      "coverage_id": "COV100"
    },
    {
      "coverage_id": "COV101"
    }
  ],
  "risks": [
    {
      "risk_id": "VEH100",
      "risk_type": "vehicle"
    },
    {
      "risk_id": "VEH101",
      "risk_type": "vehicle"
    }
  ],
  "premium": {
    "premium_amount": 185.5,
    "premium_frequency": "monthly",
    "annual_premium": 2226,
    "currency": "USD"
  },
  "billing": {
    "billing_method": "eft_ach",
    "billing_status": "current",
    "next_due_date": "2026-11-01"
  },
  "producers": [
    {
      "producer_id": "PRD123",
      "agency_id": "AGY123",
      "role": "writing_agent"
    }
  ],
  "prior_policies": [
    {
      "prior_policy_id": "PRIOR100"
    }
  ],
  "underwriting": [
    {
      "underwriting_id": "UW100"
    }
  ],
  "endorsements": [
    {
      "endorsement_id": "END100"
    }
  ],
  "policy_snapshots": [
    {
      "policy_snapshot_id": "SNAP100"
    }
  ],
  "documents": [
    {
      "document_id": "DOC100"
    }
  ],
  "claims_losses": [
    {
      "claim_loss_id": "CLM100"
    }
  ],
  "external_references": [
    {
      "system": "carrier",
      "reference_id": "987654321",
      "reference_type": "policy_number"
    }
  ]
}

Open in Validator →