Vehicle

Represents a motor vehicle or mobile risk used in an insurance Quote, Application, Policy, PriorPolicy, Coverage, Claim/Loss, or Underwriting transaction.

Vehicle describes the vehicle itself. Coverage describes how it is insured. Relationships describe who owns or uses it. The same object supports personal and commercial automobile.

Identity

vehicle_id is required. VIN, year, make, and model SHOULD be supplied whenever known. VIN is not required because a Vehicle MAY be created before the VIN is available. VIN-decoded values populate these standardized fields rather than a separate proprietary structure.

Field	Type	Required	Description
`vehicle_id`	string	Yes	Unique identifier for the Vehicle
`vin`	string	No	Vehicle Identification Number. SHOULD contain 17 characters for modern vehicles.
`year`	integer	No	Model year
`make`	string	No	Manufacturer
`model`	string	No	Model
`trim`	string	No	Trim or series
`body_style`	string	No	Vehicle body style
`vehicle_type`	enum	No	Standardized vehicle classification Allowed: passenger_car, suv, crossover, pickup, van, minivan, motorcycle, recreational_vehicle, commercial_truck, commercial_van, tractor, trailer, classic_collectible, other
`vehicle_type_description`	string	Yes*	Custom value when vehicle_type is other. Required when vehicle_type is other. MUST NOT be set otherwise.

Ownership

owners references Person or Organization objects. Each owner MUST contain person_id OR organization_id, but MUST NOT contain both. Drivers MUST NOT be embedded on Vehicle.

Field	Type	Required	Description
`ownership_status`	enum	No	How the Vehicle is owned or financed Allowed: owned, financed, leased, other
`ownership_status_description`	string	Yes*	Custom value when ownership_status is other. Required when ownership_status is other. MUST NOT be set otherwise.
`purchase_date`	string (date)	No	Date Vehicle was purchased or acquired
`purchase_price`	number	No	Vehicle purchase price

Owners

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	Ownership or registration role Allowed: owner, co_owner, lessee, registrant, other
`role_description`	string	Yes*	Custom value when role is other. Required when role is other. MUST NOT be set otherwise.

Lien / Lease

Lienholder and lessor details belong on Organization. Sensitive account information SHOULD NOT be stored unnecessarily.

Field	Type	Required	Description
lienholder_organization_id	string	No	Organization that holds the lien
lessor_organization_id	string	No	Leasing Organization
`loan_lease_account_reference`	string	No	Lender or leasing company account reference

Usage

Rideshare and delivery are explicit primary_use values because they may affect underwriting. Carrier-specific frequency or platform questions belong in Underwriting. days_driven_per_week MUST be between 0 and 7.

Field	Type	Required	Description
`primary_use`	enum	No	Primary use of Vehicle Allowed: pleasure, commute, business, farm, rideshare, delivery, commercial, other
`primary_use_description`	string	Yes*	Custom value when primary_use is other. Required when primary_use is other. MUST NOT be set otherwise.
`annual_mileage`	integer	No	Estimated annual miles driven
`current_odometer`	integer	No	Current odometer reading
`commute_one_way_miles`	number	No	One-way commute distance
`days_driven_per_week`	integer	No	Typical number of days Vehicle is driven each week

Garaging

The actual address MUST live on Address. Vehicle MUST NOT duplicate street, city, state, postal code, or country.

Field	Type	Required	Description
garaging_address_id	string	No	ID of the Address where the Vehicle is normally garaged

Characteristics

These values MAY be populated from VIN decoding or other authoritative vehicle-data providers.

Field	Type	Required	Description
`fuel_type`	enum	No	Fuel or powertrain type Allowed: gasoline, diesel, electric, hybrid, plug_in_hybrid, flex_fuel, hydrogen, other
`fuel_type_description`	string	Yes*	Custom value when fuel_type is other. Required when fuel_type is other. MUST NOT be set otherwise.
`cylinders`	integer	No	Number of engine cylinders
`doors`	integer	No	Number of doors
`drivetrain`	enum	No	Drivetrain configuration Allowed: fwd, rwd, awd, four_wheel_drive, other
`drivetrain_description`	string	Yes*	Custom value when drivetrain is other. Required when drivetrain is other. MUST NOT be set otherwise.

Safety / Security

Optional booleans. These SHOULD generally be populated through VIN decoding or vehicle-data enrichment rather than unnecessary manual entry.

Field	Type	Required	Description
`anti_lock_brakes`	boolean	No	Whether anti-lock brakes are present
`airbags`	boolean	No	Whether airbags are present
`anti_theft_device`	boolean	No	Whether an anti-theft device is present
`automatic_emergency_braking`	boolean	No	Whether automatic emergency braking is present
`lane_departure_warning`	boolean	No	Whether lane departure warning is present
`blind_spot_monitoring`	boolean	No	Whether blind spot monitoring is present
`adaptive_cruise_control`	boolean	No	Whether adaptive cruise control is present

Commercial

Optional commercial automobile fields. gvwr is in pounds. radius_of_operation is in miles. Detailed carrier commercial classifications belong in Underwriting.

Field	Type	Required	Description
`gvwr`	number	No	Manufacturer-rated maximum loaded vehicle weight in pounds
`vehicle_use_class`	enum	No	Commercial vehicle use class Allowed: service, retail, commercial, contractor, delivery, transportation, farm, emergency, other
`vehicle_use_class_description`	string	Yes*	Custom value when vehicle_use_class is other. Required when vehicle_use_class is other. MUST NOT be set otherwise.
`radius_of_operation`	number	No	Typical maximum operating radius in miles
`stated_value`	number	No	Stated monetary Vehicle value when applicable

Currency

currency is required when purchase_price or stated_value is supplied.

Field	Type	Required	Description
`currency`	string	No	ISO 4217 currency code

External References

external_references maps the Vehicle to identifiers from carriers, VIN decoders, comparative raters, DMV/data providers, 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

vehicle_id MUST be supplied. VIN, year, make, and model SHOULD be supplied whenever known.
One Vehicle object supports both personal and commercial automobile. Commercial 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.
VIN-decoded attributes MUST populate standardized Vehicle fields rather than a separate proprietary structure.
Vehicle MUST NOT contain Coverage limits, deductibles, or coverage selections.
Coverage references Vehicle through applies_to[] with target_type vehicle.
Drivers MUST NOT be embedded inside Vehicle. Driver relationships belong on the insurance transaction.
Each owner MUST contain person_id OR organization_id, but MUST NOT contain both.
Lienholders and lessors SHOULD reference Organization.
garaging_address_id MUST reference Address. Vehicle MUST NOT duplicate address fields.
days_driven_per_week MUST be an integer from 0 to 7.
Mileage values MUST NOT be negative.
gvwr is represented in pounds. radius_of_operation is represented in miles.
currency MUST use ISO 4217 and is required when purchase_price or stated_value is supplied.
Carrier-specific underwriting questions belong in Underwriting, not Vehicle.
Dates MUST use ISO 8601 date format (YYYY-MM-DD).
Health insurance and group insurance MUST NOT appear on Vehicle.

{
  "vehicle_id": "VEH-100",
  "vin": "1HGBH41JXMN109186",
  "year": 2026,
  "make": "Lexus",
  "model": "ES 350",
  "trim": "F Sport",
  "body_style": "Sedan",
  "vehicle_type": "passenger_car",
  "ownership_status": "financed",
  "purchase_date": "2026-04-15",
  "purchase_price": 52000,
  "currency": "USD",
  "owners": [
    {
      "person_id": "PER-100",
      "role": "owner"
    }
  ],
  "lienholder_organization_id": "ORG-BANK-100",
  "primary_use": "commute",
  "annual_mileage": 12000,
  "current_odometer": 6250,
  "commute_one_way_miles": 14,
  "days_driven_per_week": 5,
  "garaging_address_id": "ADDR-100",
  "fuel_type": "gasoline",
  "cylinders": 6,
  "doors": 4,
  "drivetrain": "fwd",
  "anti_lock_brakes": true,
  "airbags": true,
  "anti_theft_device": true,
  "automatic_emergency_braking": true,
  "lane_departure_warning": true,
  "blind_spot_monitoring": true,
  "adaptive_cruise_control": true
}

Open in Validator →