Property

Represents a physical real property, building, dwelling, structure, premises, or land risk used in an insurance Quote, Application, Policy, PriorPolicy, Coverage, Claim/Loss, or Underwriting transaction.

Property describes the physical property and its characteristics. Coverage describes how it is insured. Underwriting describes insurance-specific risk evaluation. The same object supports residential, rental, commercial, and farm insurance.

Identity

property_id, address_id, and property_type are required. The physical address MUST live on Address. Property MUST NOT duplicate street, unit, city, state, postal code, or country.

Field	Type	Required	Description
`property_id`	string	Yes	Unique Fat Agent Standard Property identifier
address_id	string	Yes	Reference to the property's Address
`property_type`	enum	Yes	Standardized property classification Allowed: single_family, condo, townhouse, multifamily, apartment, manufactured_home, mobile_home, commercial, farm, vacant_land, other
`property_type_description`	string	Yes*	Custom value when property_type is other. Required when property_type is other. MUST NOT be set otherwise.

Construction

Physical construction facts. basement_finished_percentage MUST be between 0 and 100 and MUST NOT be set when basement is false.

Field	Type	Required	Description
`year_built`	integer	No	Four-digit calendar year the Property was built
`square_feet`	number	No	Total square footage
`stories`	number	No	Number of stories
`construction_type`	enum	No	Construction classification Allowed: frame, masonry, masonry_veneer, fire_resistive, modified_fire_resistive, joisted_masonry, non_combustible, modified_non_combustible, mixed, manufactured, other
`construction_type_description`	string	Yes*	Custom value when construction_type is other. Required when construction_type is other. MUST NOT be set otherwise.
`exterior_type`	enum	No	Exterior finish Allowed: vinyl_siding, aluminum_siding, wood_siding, fiber_cement, brick, stone, stucco, masonry, metal, mixed, other
`exterior_type_description`	string	Yes*	Custom value when exterior_type is other. Required when exterior_type is other. MUST NOT be set otherwise.
`foundation_type`	enum	No	Foundation type Allowed: basement, crawlspace, slab, pier, raised, other
`foundation_type_description`	string	Yes*	Custom value when foundation_type is other. Required when foundation_type is other. MUST NOT be set otherwise.
`basement`	boolean	No	Whether a basement exists
`basement_finished_percentage`	number	No	Finished basement percentage in percentage points. MUST be between 0 and 100.
`roof_type`	enum	No	Roof covering Allowed: asphalt_shingle, architectural_shingle, metal, tile, slate, wood_shake, flat, membrane, built_up, other
`roof_type_description`	string	Yes*	Custom value when roof_type is other. Required when roof_type is other. MUST NOT be set otherwise.
`roof_year`	integer	No	Year the current roof was installed
`garage_type`	enum	No	Garage configuration Allowed: attached, detached, built_in, carport, none, other
`garage_type_description`	string	Yes*	Custom value when garage_type is other. Required when garage_type is other. MUST NOT be set otherwise.
`garage_spaces`	integer	No	Number of vehicle spaces

Occupancy / Use

Percentage values use percentage points: 25 means 25%. Detailed business-activity questions belong in Underwriting.

Field	Type	Required	Description
`occupancy_type`	enum	No	How the Property is occupied or used Allowed: primary_residence, secondary_residence, seasonal, owner_occupied, tenant_occupied, rental, short_term_rental, vacant, under_construction, commercial, farm, mixed_use, other
`occupancy_type_description`	string	Yes*	Custom value when occupancy_type is other. Required when occupancy_type is other. MUST NOT be set otherwise.
`number_of_units`	integer	No	Number of residential or commercial units
`number_of_occupants`	integer	No	Number of occupants when known
`vacancy_percentage`	number	No	Percentage of property currently vacant
`business_on_premises`	boolean	No	Whether business activity occurs on premises

Systems

Physical building-system facts. roof_year is the current roof installation year. roof_update_year MAY be used when a substantial roof update did not constitute complete replacement. Carrier eligibility questions belong in Underwriting.

Field	Type	Required	Description
`heating_type`	enum	No	Heating system type Allowed: forced_air, boiler, heat_pump, electric, radiant, geothermal, wood, pellet, oil, propane, other
`heating_type_description`	string	Yes*	Custom value when heating_type is other. Required when heating_type is other. MUST NOT be set otherwise.
`cooling_type`	enum	No	Cooling system type Allowed: central_air, heat_pump, window_units, evaporative, none, other
`cooling_type_description`	string	Yes*	Custom value when cooling_type is other. Required when cooling_type is other. MUST NOT be set otherwise.
`electrical_type`	enum	No	Electrical system type Allowed: circuit_breakers, fuses, knob_and_tube, aluminum_wiring, copper_wiring, mixed, other
`electrical_type_description`	string	Yes*	Custom value when electrical_type is other. Required when electrical_type is other. MUST NOT be set otherwise.
`plumbing_type`	enum	No	Plumbing material or system type Allowed: copper, pvc, cpvc, pex, galvanized, polybutylene, cast_iron, mixed, other
`plumbing_type_description`	string	Yes*	Custom value when plumbing_type is other. Required when plumbing_type is other. MUST NOT be set otherwise.
`water_heater_type`	enum	No	Water heater type Allowed: gas, electric, tankless, heat_pump, solar, other
`water_heater_type_description`	string	Yes*	Custom value when water_heater_type is other. Required when water_heater_type is other. MUST NOT be set otherwise.
`electrical_update_year`	integer	No	Most recent substantial electrical update year
`plumbing_update_year`	integer	No	Most recent substantial plumbing update year
`hvac_update_year`	integer	No	Most recent substantial HVAC update year
`roof_update_year`	integer	No	Most recent substantial roof update year when not a complete replacement

Protection / Safety

Safety device fields are optional booleans. Distances are expressed in miles. protection_class SHOULD preserve the authoritative classification supplied by the carrier, rating provider, municipality, or protection-class data provider.

Field	Type	Required	Description
`smoke_detectors`	boolean	No	Whether smoke detectors are present
`fire_alarm`	boolean	No	Whether a fire alarm is present
`burglar_alarm`	boolean	No	Whether a burglar alarm is present
`automatic_sprinklers`	boolean	No	Whether automatic sprinklers are present
`deadbolts`	boolean	No	Whether deadbolts are present
`distance_to_fire_hydrant`	number	No	Distance to the nearest fire hydrant in miles
`distance_to_fire_station`	number	No	Distance to the nearest fire station in miles
`protection_class`	string	No	Authoritative protection class as supplied by the source

Property Features / Hazards

Optional booleans for physical presence. Detailed risk questions such as pool fencing, animal breed, or bite history belong in Underwriting. business_on_premises is documented under Occupancy / Use.

Field	Type	Required	Description
`swimming_pool`	boolean	No	Whether a swimming pool is present
`trampoline`	boolean	No	Whether a trampoline is present
`wood_stove`	boolean	No	Whether a wood stove is present
`fireplace`	boolean	No	Whether a fireplace is present
`solar_panels`	boolean	No	Whether solar panels are present
`animals_present`	boolean	No	Whether animals are present

Valuation

replacement_cost is a property valuation and MUST remain distinct from Coverage.limit. market_value MUST NOT be treated as an insurance coverage limit. currency is required when any monetary Property value is supplied.

Field	Type	Required	Description
`purchase_date`	string (date)	No	Date the Property was purchased or acquired
`purchase_price`	number	No	Property acquisition price
`market_value`	number	No	Estimated or reported market value. MUST NOT be treated as a Coverage limit.
`replacement_cost`	number	No	Estimated cost to rebuild or replace the physical property. MUST remain distinct from Coverage.limit.
`currency`	string	No	ISO 4217 currency code. Required when purchase_price, market_value, or replacement_cost is supplied.

Commercial / Farm

Optional commercial and farm fields. Separately insured or materially distinct structures SHOULD generally receive their own property_id. Acreage is in acres. owner_occupied_percentage and tenant_occupied_percentage MUST each be between 0 and 100, and MUST NOT combine to more than 100.

Field	Type	Required	Description
`building_use`	enum	No	Primary physical use of a commercial or farm property Allowed: office, retail, restaurant, warehouse, industrial, manufacturing, medical, hospitality, residential, mixed_use, agricultural, storage, vacant, other
`building_use_description`	string	Yes*	Custom value when building_use is other. Required when building_use is other. MUST NOT be set otherwise.
`commercial_square_feet`	number	No	Square footage used for commercial operations when different from total square_feet
`acreage`	number	No	Total acreage associated with the Property
`owner_occupied_percentage`	number	No	Owner-occupied percentage in percentage points
`tenant_occupied_percentage`	number	No	Tenant-occupied percentage in percentage points

Improvements

Significant building improvements. Each item requires improvement_type and year.

Field Type Required Description

Field	Type	Required	Description
`improvement_type`	enum	Yes	Type of improvement Allowed: roof, electrical, plumbing, hvac, structural, addition, renovation, fire_protection, other
`improvement_type_description`	string	Yes*	Custom value when improvement_type is other. Required when improvement_type is other. MUST NOT be set otherwise.
`year`	integer	Yes	Four-digit calendar year of the improvement

improvement_type

enum

Yes

Type of improvement

Allowed: roof, electrical, plumbing, hvac, structural, addition, renovation, fire_protection, other

improvement_type_description

string

Yes*

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

year

integer

Yes

Four-digit calendar year of the improvement

External References

external_references maps the Property to identifiers from carriers, replacement-cost estimators, county auditors, property-data providers, comparative raters, or AMS records.

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

property_id, address_id, and property_type MUST be supplied.
One Property object supports residential, rental, commercial, farm, and vacant land. Commercial and farm fields are optional.
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.
address_id MUST reference Address. Property MUST NOT duplicate address fields.
Vehicle, Person, and Organization facts MUST NOT be duplicated inside Property.
Coverage limits and deductibles MUST NOT be stored in Property.
Coverage references Property through applies_to[] with target_type property.
replacement_cost is a property valuation and MUST remain distinct from Coverage.limit.
market_value MUST NOT be treated as an insurance coverage limit.
Physical facts belong in Property. Insurance-specific eligibility and risk questions belong in Underwriting.
Basic physical hazard presence MAY be represented in Property. Detailed hazard characteristics belong in Underwriting.
Separately identifiable or separately insured structures SHOULD generally receive their own property_id.
basement_finished_percentage MUST be between 0 and 100 and MUST NOT be set when basement is false.
Percentage fields use percentage-point values: 75 means 75%.
When owner_occupied_percentage and tenant_occupied_percentage are both supplied, their combined value MUST NOT exceed 100.
Distances are represented in miles. Acreage is represented in acres.
currency MUST use ISO 4217 and is required when purchase_price, market_value, or replacement_cost is supplied.
Years MUST use four-digit calendar years.
Dates MUST use ISO 8601 date format (YYYY-MM-DD).
Health insurance and group insurance MUST NOT appear on Property.

{
  "property_id": "PROP-100",
  "address_id": "ADDR-100",
  "property_type": "single_family",
  "year_built": 2005,
  "square_feet": 3200,
  "stories": 2,
  "construction_type": "masonry_veneer",
  "exterior_type": "brick",
  "foundation_type": "basement",
  "basement": true,
  "basement_finished_percentage": 75,
  "roof_type": "architectural_shingle",
  "roof_year": 2022,
  "garage_type": "attached",
  "garage_spaces": 2,
  "occupancy_type": "primary_residence",
  "number_of_units": 1,
  "number_of_occupants": 4,
  "vacancy_percentage": 0,
  "business_on_premises": false,
  "heating_type": "forced_air",
  "cooling_type": "central_air",
  "electrical_type": "circuit_breakers",
  "plumbing_type": "pex",
  "water_heater_type": "gas",
  "smoke_detectors": true,
  "fire_alarm": true,
  "burglar_alarm": true,
  "automatic_sprinklers": false,
  "deadbolts": true,
  "distance_to_fire_hydrant": 0.1,
  "distance_to_fire_station": 2.4,
  "protection_class": "4",
  "swimming_pool": false,
  "trampoline": false,
  "wood_stove": false,
  "fireplace": true,
  "solar_panels": false,
  "animals_present": true,
  "purchase_date": "2018-06-15",
  "purchase_price": 425000,
  "market_value": 525000,
  "replacement_cost": 610000,
  "currency": "USD"
}

Open in Validator →