Fat Agent Standard / P&C

v1.0

Claim / Loss

Represents an insurance claim, reported loss, or historical loss event associated with a Person, Organization, Vehicle, Property, Policy, PriorPolicy, Coverage, or other insured risk.

Claim / Loss describes what happened, when it happened, what was affected, and the financial/outcome history of the event. A Claim / Loss MAY exist even when no insurance claim was filed. The same object is used across all supported lines of business.

Identity

claim_loss_id, record_type, and loss_date are required. record_type distinguishes a filed insurance claim from a known loss with no claim. A loss_only record does not require status. claim_number is optional because loss-only events may not have one.

Field	Type	Required	Description
`claim_loss_id`	string	Yes	Unique Claim / Loss identifier
`claim_number`	string	No	Carrier or administrator claim number
`record_type`	enum	Yes	Whether this record is a filed claim or a known loss without a claim Allowed: claim, loss_only
`status`	enum	No	Current claim/loss lifecycle status. Not required for loss_only. Allowed: reported, open, under_investigation, pending, closed, reopened, denied, withdrawn, settled, other
`status_description`	string	Yes*	Custom value when status is other. Required when status is other. MUST NOT be set otherwise.
`loss_date`	string (date)	Yes	Date the loss occurred
`loss_time`	string (time)	No	Time the loss occurred
`reported_date`	string (date)	No	Date the claim/loss was reported
`closed_date`	string (date)	No	Date the claim was closed

Classification

line_of_business SHOULD be supplied whenever known. unknown SHOULD be used when the cause has not been determined. other SHOULD only be used when the cause is known but no standardized value accurately represents it. description SHOULD summarize the incident without replacing structured fields.

Field	Type	Required	Description
`line_of_business`	enum	No	Insurance line associated with the Claim / Loss 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.
`loss_type`	enum	No	General type of loss Allowed: bodily_injury, property_damage, collision, comprehensive, theft, vandalism, fire, smoke, water_damage, wind, hail, lightning, flood, earthquake, weather, liability, medical, disability, death, long_term_care, business_interruption, workers_compensation, cyber, crime, other
`loss_type_description`	string	Yes*	Custom value when loss_type is other. Required when loss_type is other. MUST NOT be set otherwise.
`cause_of_loss`	enum	No	Primary known cause of the event Allowed: collision, theft, vandalism, fire, smoke, water, freezing, wind, hail, lightning, flood, earthquake, falling_object, animal, glass_breakage, equipment_failure, mechanical_failure, electrical, weather, negligence, illness, injury, death, occupational, cyber_event, unknown, other
`cause_of_loss_description`	string	Yes*	Custom value when cause_of_loss is other. Required when cause_of_loss is other. MUST NOT be set otherwise.
`description`	string	No	Concise human-readable summary of the loss

Catastrophe

catastrophe_id MAY preserve an industry, carrier, administrator, or Fat Agent catastrophe identifier.

Field	Type	Required	Description
`catastrophe_indicator`	boolean	No	Whether the loss is associated with a catastrophe event
`catastrophe_id`	string	No	Catastrophe identifier
`catastrophe_name`	string	No	Catastrophe name

Insurance

A historical loss MAY reference prior_policy_id. A loss_only event MAY have neither a Policy nor PriorPolicy when no insurance contract was involved or the insurance information is unknown.

Field	Type	Required	Description
policy_id	string	No	Related Policy
prior_policy_id	string	No	Related PriorPolicy
coverage_ids	array[string]	No	Coverage objects associated with this Claim / Loss

Parties

Each party MUST contain person_id OR organization_id, but MUST NOT contain both. The same Person MAY have multiple roles.

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 role in the Claim / Loss Allowed: claimant, insured, named_insured, owner, driver, passenger, injured_party, deceased, beneficiary, responsible_party, third_party, witness, other
`role_description`	string	Yes*	Custom value when role is other. Required when role is other. MUST NOT be set otherwise.

Risks

Claim / Loss MUST reference Vehicle, Property, Person, or Organization rather than duplicate those objects.

Field Type Required Description

Field	Type	Required	Description
`risk_id`	string	Yes	ID of the related risk object
`risk_type`	enum	Yes	Type of related risk object Allowed: vehicle, property, person, organization, 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 related risk object

risk_type

enum

Yes

Type of related risk object

Allowed: vehicle, property, person, organization, other

risk_type_description

string

Yes*

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

Incident

These fields describe the event. Detailed injury diagnoses, treatment, medical records, repair estimates, photographs, and police reports belong in Underwriting, Document / Evidence, or external claims systems.

Field	Type	Required	Description
`bodily_injury_indicator`	boolean	No	Whether bodily injury occurred
`property_damage_indicator`	boolean	No	Whether property damage occurred
`fatality_indicator`	boolean	No	Whether the event involved a fatality
`number_injured`	integer	No	Number of people injured
`number_of_vehicles`	integer	No	Number of vehicles involved
`number_of_properties`	integer	No	Number of properties involved

Liability

Fault information MUST represent supplied, reported, or established information. Do not infer fault from the loss description. Responsible parties are represented through parties[]. fault_percentage uses percentage points: 50 means 50%.

Field	Type	Required	Description
`at_fault_indicator`	boolean	No	Whether the insured or applicable party was determined to be at fault
`fault_percentage`	number	No	Established or reported allocation of fault. MUST be between 0 and 100.
`liability_status`	enum	No	Liability determination status Allowed: not_applicable, undetermined, investigation_pending, insured_at_fault, insured_not_at_fault, shared_fault, liability_accepted, liability_denied, other
`liability_status_description`	string	Yes*	Custom value when liability_status is other. Required when liability_status is other. MUST NOT be set otherwise.

Financials

Preserve carrier or claims-system values when available. Fat Agent Standard MUST NOT automatically assume incurred_amount equals amount_paid plus amount_reserved. currency is required when any monetary Claim / Loss value is supplied.

Field	Type	Required	Description
`amount_claimed`	number	No	Amount requested or claimed when known
`amount_paid`	number	No	Cumulative claim payments made as of the current record
`amount_reserved`	number	No	Current outstanding claim reserve when available
`incurred_amount`	number	No	Reported total incurred amount when supplied by the carrier or claims system
`deductible`	number	No	Deductible actually associated with this loss event
`recovery_amount`	number	No	Recoveries associated with the loss
`subrogation_amount`	number	No	Amounts recovered through subrogation
`currency`	string	No	ISO 4217 currency code. Required when any monetary Claim / Loss value is supplied.

Outcome

status describes where the claim is in its lifecycle. disposition describes its financial or claims outcome. These MUST remain separate concepts.

Field Type Required Description

Field	Type	Required	Description
`disposition`	enum	No	Final or current claim outcome Allowed: paid, partially_paid, settled, denied, withdrawn, closed_without_payment, closed_with_payment, pending, other
`disposition_description`	string	Yes*	Custom value when disposition is other. Required when disposition is other. MUST NOT be set otherwise.

disposition

enum

Final or current claim outcome

Allowed: paid, partially_paid, settled, denied, withdrawn, closed_without_payment, closed_with_payment, pending, other

disposition_description

string

Yes*

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

Documents

Police reports, loss runs, estimates, photographs, and similar evidence MUST be referenced rather than embedded.

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

External References

external_references maps the Claim / Loss to identifiers from carriers, claims administrators, loss-run sources, comparative raters, AMS records, or catastrophe systems.

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

Validation Rules

claim_loss_id, record_type, and loss_date MUST be supplied.
record_type MUST distinguish claim from loss_only. A loss MAY exist without an insurance claim being filed.
One Claim / Loss object is used across all supported lines of business.
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.
line_of_business SHOULD be supplied whenever known.
Claim / Loss MAY reference Policy, PriorPolicy, and Coverage by ID. Do NOT duplicate those objects.
Each party MUST contain person_id OR organization_id, but MUST NOT contain both.
Risks MUST reference Vehicle, Property, Person, or Organization rather than duplicate those objects.
status and disposition MUST remain separate concepts.
fault_percentage MUST be between 0 and 100. Fault MUST represent supplied, reported, or established information.
Fat Agent Standard MUST NOT automatically derive incurred_amount from amount_paid and amount_reserved.
currency MUST use ISO 4217 and is required when any monetary Claim / Loss value is supplied.
Historical Claim / Loss records are additive and MUST NOT be overwritten by newer losses.
Supporting evidence belongs in Document / Evidence and MUST be referenced through documents[].
Insurance-specific evaluation of loss history belongs in Underwriting.
Percentage fields use percentage-point values: 50 means 50%.
Dates MUST use ISO 8601 date format (YYYY-MM-DD). Times MUST use ISO 8601-compatible time format.
Health insurance and group insurance MUST NOT appear on Claim / Loss.

{
  "claim_loss_id": "CLM-AUTO-100",
  "claim_number": "AUTO-554821",
  "record_type": "claim",
  "status": "closed",
  "loss_date": "2026-05-10",
  "loss_time": "16:35:00",
  "reported_date": "2026-05-10",
  "closed_date": "2026-06-21",
  "line_of_business": "personal_auto",
  "loss_type": "collision",
  "cause_of_loss": "collision",
  "description": "Insured vehicle collided with another vehicle while changing lanes.",
  "catastrophe_indicator": false,
  "policy_id": "POL-AUTO-100",
  "coverage_ids": [
    "COV-COLLISION-100",
    "COV-BI-100"
  ],
  "parties": [
    {
      "person_id": "PER-100",
      "role": "insured"
    },
    {
      "person_id": "PER-100",
      "role": "driver"
    },
    {
      "person_id": "PER-200",
      "role": "claimant"
    }
  ],
  "risks": [
    {
      "risk_id": "VEH-100",
      "risk_type": "vehicle"
    },
    {
      "risk_id": "VEH-200",
      "risk_type": "vehicle"
    }
  ],
  "bodily_injury_indicator": true,
  "property_damage_indicator": true,
  "fatality_indicator": false,
  "number_injured": 1,
  "number_of_vehicles": 2,
  "number_of_properties": 0,
  "at_fault_indicator": true,
  "fault_percentage": 100,
  "liability_status": "insured_at_fault",
  "amount_claimed": 18500,
  "amount_paid": 14500,
  "amount_reserved": 0,
  "incurred_amount": 14500,
  "deductible": 1000,
  "currency": "USD",
  "disposition": "closed_with_payment"
}

Open in Validator →