# Describing a vehicle

This page explains how you describe a vehicle in a valuation or normalization request, how your inputs combine, and how to read the vehicle that comes back. The [Vehicle object](/docs/reference/vehicles#the-vehicle-object) and [VehicleInput](/docs/reference/vehicles#vehicleinput-describing-a-vehicle) are specified in the vehicles reference.

## Inputs and the returned vehicle

There are two sides:

- **The input** is what you send: `vehicle` in the request (a VehicleInput), plus any `description` text and `images`. Every field is optional apart from what is needed to identify the vehicle, and unknown values should be left out rather than guessed. You can send the attributes on this page, or an [AutoUncle Vehicle Schema (AVS)](https://github.com/AutoUncle/avs) vehicle document, such as the `vehicle` another call returned.
- **The returned vehicle** is the [Vehicle](/docs/reference/vehicles#the-vehicle-object) that was identified and, for a valuation, priced: an AVS vehicle document with catalogue IDs and names for every level that could be identified, its specification, equipment, registration and odometer. Beside it, [`identification`](/docs/reference/vehicles#identification) says how well it was identified and, in `fields`, where each value came from.

Always read the returned vehicle. If it is not the car you meant, the price is not for that car.

## How inputs combine

You can mix catalogue IDs, structured attributes, text and photos in one request. They are combined in this order of precedence:

1. **Catalogue IDs** in `vehicle.catalogue` (`brand_id`, `model_id`, `generation_id`, `drivetrain_id`, `equipment_variant_id`). They are used as given. Send any levels you know; a lower level fills in its parents, so a `drivetrain_id` alone identifies the brand, model and generation too. All IDs must belong to one hierarchy, or the valuation is refused with `catalogue_id_conflict`.
2. **Structured attributes** such as `make`, `model`, `variant`, `fuel`, `transmission`, `power_hp` and `model_year`. They are matched against the catalogue and always win over anything read from text or photos.
3. **Text and photos.** `description` is read by deterministic parsing rules and, for live keys when the deployment has it configured, by automated interpretation. Photos are used only by automated interpretation. Neither ever runs for test keys.
4. **Catalogue data** for the resolved drivetrain, such as fuel, power and engine size, fills attributes you did not send.
5. **Defaults and assumptions**, marked `assumed` in `identification.fields` and reported in `warnings`. Mileage is never assumed unless you set `options.allow_mileage_estimation: true`, and equipment never unless you set `options.allow_equipment_estimation: true` (see [assumed equipment](/docs/valuations#assumed-equipment)).

Names are matched as the catalogue spells them; common variants such as `Volkswagen` for the catalogue brand `VW` are recognized when you send them as structured `make`. In practice, deterministic text parsing alone often cannot identify a vehicle from a description, so with a test key (or `no_ai`/`strict`) send at least `make`, `model`, `model_year` and `mileage` as structured fields. See [free text and photos](/docs/guides/text-and-photos).

## Identity

| Field | Use it for |
| --- | --- |
| `catalogue.*_id` | The exact vehicle, from the [catalogue](/docs/catalogue). The most precise input. |
| `make`, `model` | Names from your source, such as `VW` and `Golf`. |
| `variant` | Free-text engine or trim designation, such as `1.5 TSI DSG` or `GTI Performance`. Helps pick the drivetrain. |
| `body` | Body style, such as `hatchback`, `estate` or `SUV`. Unknown labels may stay unresolved. |
| `model_year`, `first_registration` | The registration year as an integer, or the first registration date as `YYYY-MM-DD`. When both are sent, the year of `first_registration` is used. Do not derive a date from a photograph. |

Every attribute on this page also has a place in an AVS vehicle document, such as `identity.brand.name` for `make` or `specification.powertrain.energy` for `fuel`; the [VehicleInput table](/docs/reference/vehicles#vehicleinput-describing-a-vehicle) lists them.

## Mileage and units

`vehicle.mileage` always has a value and an explicit unit:

```json
{
  "mileage": { "value": 45000, "unit": "km" }
}
```

| Unit | Meaning |
| --- | --- |
| `km` | Kilometres |
| `mi` | Miles |
| `mil` | Scandinavian miles of 10 km, as used in Sweden |

Send the odometer reading in the unit you have; it is converted to the market's unit before scoring. The returned vehicle reports it in kilometres, as AVS `vehicle.odometer.km`, whatever the market. Do not convert it yourself and then send the original unit. `0` is a valid mileage. Missing mileage is refused with `missing_mileage` unless you opt in to the fixed 96,000 km baseline; see [refusals & missing mileage](/docs/guides/refusals-and-mileage).

Other units are fixed:

- `power_hp` is in horsepower. Convert kilowatts first (hp = kW × 1.35962, rounded), or send an AVS document with `specification.powertrain.powerKw` and it is converted for you.
- `engine_size_l` is in litres, for example `1.5`. Omit it for fully electric vehicles.
- `battery_kwh` is the traction battery capacity in kWh.
- `electric_range_km` is always in kilometres, whatever the market.

## Drivetrain and specification

| Field | Values |
| --- | --- |
| `fuel` | Prefer the values from [`GET /v1/catalogue/enums`](/docs/reference/catalogue#get-v1-catalogue-enums): `petrol`, `diesel`, `electric`, `hybrid`, `plug_in_hybrid_petrol`, `plug_in_hybrid_diesel`, `lpg`, `cng`, `hydrogen`. Source labels are normalized when recognized. |
| `transmission` | `manual` or `automatic`. Omit it when unknown: an omitted gearbox is not treated as manual. |
| `drive` | `fwd`, `rwd`, `awd` or `4wd`. |
| `doors`, `seats` | Integers from the specification. |
| `color` | Exterior color or color family from your source. |
| `condition` | A known numeric grade from 0 to 4. Omit it rather than inventing a grade. |

## Equipment

`equipment` is a list of feature keys from [`GET /v1/catalogue/enums`](/docs/reference/catalogue#get-v1-catalogue-enums), such as `INFOTAINMENT_NAVIGATION`, `CAMERA_PARKING_REAR` or `BATTERY_HEAT_PUMP`. Up to 150 keys, as strings. The earlier keys such as `has_gps` are still accepted. Unrecognized keys are ignored and produce an `equipment_not_recognized` warning.

A returned Vehicle lists its equipment as AVS features in `equipment.features`: `{ "key": "EXTERIOR_TOWBAR_FIXED", "name": "Fixed Trailer Hitch", "category": "EXTERIOR", "ids": [{ "scheme": "autouncle", "value": "f-9e2bf372ce4d984dd6722039" }], "availability": "fitted" }`. The key is the most specific feature the listing or your request states (an adaptive cruise control rather than plain cruise control). A feature that is not listed is unknown, not absent. With `options.allow_equipment_estimation: true`, features assumed for the vehicle are listed too, with `availability: "unknown"` and marked `assumed` in `identification.fields`.

## Flags

`flags` holds boolean risk and eligibility attributes, up to 30 entries. The valuation model covers ordinary used cars for sale, so these ten flags make a vehicle ineligible, and they are the only flags with an effect:

| Flags | Effect when `true` |
| --- | --- |
| `is_damaged`, `has_new_engine`, `is_leasing_price`, `has_no_battery`, `is_auction_car`, `is_commercial_car`, `price_is_leasing_rate` | Refused with `unsupported_vehicle` in every market. |
| `has_no_tax` | Refused with `unsupported_vehicle` in DK, SE, DE, ES, AT and PT. |
| `has_yellow_plates`, `is_camper_version` | Refused with `unsupported_vehicle` in DK. |

Flags that are `false` change nothing. Any other flag name is ignored and the result carries a `flags_not_recognized` warning naming it; a market-specific flag sent for another market, such as `has_yellow_plates` in DE, is ignored with a `flags_not_applicable` warning. Each flag is also described in the [request fields](#valuation-request-fields).

## VIN and registration plate

With a live key, a `vin` or `registration_plate` is looked up before the vehicle is resolved, and what the lookup finds fills in the attributes you left out.

| You send | Market | Looked up in | Fills |
| --- | --- | --- | --- |
| `registration_plate` | DK | Danish Motor Register (DMR) | make, model, variant, fuel, transmission, body, colour, doors, first registration, model year, power and engine size |
| `vin` | DK | Danish Motor Register, then VIN decoding if the register does not know the VIN | as above, or make, model and model year when decoded |
| `vin` | other markets | VIN decoding | make, model and model year |
| either | DE, IT, ES | not looked up | nothing |
| `registration.hsn` and `registration.tsn` | any | Kraftfahrt-Bundesamt type snapshot | make and model |

The identifiers can also be sent as `registration.vin` and `registration.registration_plate`, or in an AVS document as `vehicle.vin` and `vehicle.registration.plate`. When you send both, the plate is looked up; the VIN is decoded instead only where plates cannot be looked up. Test keys never look anything up.

**Your values win.** A looked-up value only fills an attribute you did not send. If it disagrees with one you did send (another model, fuel, power or year), your value is used and the result carries a `registry_conflict` warning naming the fields; check them or the identifier. A year you send settles both `model_year` and `first_registration`. The register's odometer readings from past inspections are not the current mileage and are never used, so send `vehicle.mileage` as usual.

**Provenance.** Each looked-up value has an entry in `identification.fields` with `source: "registry"`, `basis: "observed"` and the `source_id` of the source that supplied it (`dk_vehicle_register`, `vin_decoding` or `de_type_approval_codes`), and the source is listed in `attributions`. A catalogue identity matched from looked-up names is still `catalogue_match`, with `evidence_source_id` naming the source whose names it was matched from.

**When a lookup cannot be used,** the valuation goes ahead with the attributes you sent, and a warning says why:

| Warning | Meaning |
| --- | --- |
| `registry_lookup_not_available` | Lookups are not offered in this market (DE, IT, ES), or plates cannot be looked up in it yet. |
| `registry_identifier_invalid` | The VIN or plate is not in a valid format, so nothing was looked up. |
| `registry_no_match` | The register or decoder has no record for it. |
| `registry_lookup_failed` | The lookup timed out or was unavailable. |
| `registry_lookup_not_used` | A test key: identifiers are never looked up. |

If the identifier was your only description of the vehicle (no make, model, catalogue IDs, description or photos) and the lookup times out or is unavailable, the valuation **fails** instead, with `resolution_timeout` or `resolution_unavailable` and `service: "vehicle_registry"`, retryable and without a charge. If it simply finds nothing, the request is refused as `vehicle_not_identified`.

A lookup is included in the valuation's or normalization's credit; it costs nothing extra. To look an identifier up on its own, use the [vehicle lookup endpoints](/docs/reference/vehicles#vehicle-lookups). It shares the [processing budget](/docs/valuations#processing-budget). The raw VIN and plate are not stored in valuation records.

## Drive side

`drive_side` (`left` or `right`) is part of the contract, but in this version a request that includes it fails with `500 internal_error`. Omit it until the [changelog](/docs/changelog) announces a fix. No credit is used when this happens.

## Valuation request fields

Every request field, generated from the OpenAPI contract:

| Field | Type | Description |
| --- | --- | --- |
| `country` | string | Valuation market as an ISO 3166-1 alpha-2 code, such as DK, DE or GB. The market selects its own vehicle data, currency and mileage conventions. 2 to 10 characters. |
| `vehicle` | object | A vehicle as a request describes it: either an AVS vehicle document (any `vehicle` an endpoint returned, posted back unchanged, or one you build), recognized by its `avs` member, or the vehicle's attributes (VehicleAttributes). Omit unknown values instead of guessing. |
| `vehicle.make` | string | Vehicle manufacturer or make, such as VW or BMW. Catalogue brand_id avoids ambiguous names. At most 200 characters. |
| `vehicle.model` | string | Model name as supplied by your source, such as Golf. Catalogue model_id avoids name mapping and spelling ambiguity. At most 200 characters. |
| `vehicle.variant` | string | Free-text engine, trim or version designation, such as 1.5 TSI DSG. This can help resolve a more precise catalogue identity. At most 200 characters. |
| `vehicle.body` | string | Body style or source label, such as hatchback, estate or SUV. Unknown labels may remain unresolved. At most 200 characters. |
| `vehicle.fuel` | string | Fuel or electrification type: petrol, diesel, electric, hybrid (a full hybrid that cannot be plugged in), plug_in_hybrid_petrol, plug_in_hybrid_diesel, lpg, cng, ethanol or hydrogen, as listed by /v1/catalogue/enums. Source labels are also normalized when recognized. At most 200 characters. |
| `vehicle.color` | string | Exterior colour or colour family from your source. Colour is normalized when possible. At most 200 characters. |
| `vehicle.catalogue` | object | Stable AutoUncle catalogue UUIDs. Supply any known levels; IDs must describe one consistent vehicle hierarchy. |
| `vehicle.catalogue.brand_id` | string | Make UUID returned by the brands catalogue endpoint. All lower-level IDs must belong to this make. 1 to 100 characters. |
| `vehicle.catalogue.model_id` | string | Model UUID returned by the models catalogue endpoint. Virtual model aliases are resolved to their canonical model for scoring. 1 to 100 characters. |
| `vehicle.catalogue.generation_id` | string | Generation UUID returned for the selected model. This identifies the vehicle generation and body variant. 1 to 100 characters. |
| `vehicle.catalogue.drivetrain_id` | string | Drivetrain UUID returned for the selected generation. Identifies the engine and transmission variant and improves identity precision. 1 to 100 characters. |
| `vehicle.catalogue.equipment_variant_id` | string | Equipment or trim variant UUID returned for the make. It must belong to the same make as the other catalogue IDs. 1 to 100 characters. |
| `vehicle.model_year` | integer | Known registration or model year as a four-digit integer. first_registration takes precedence when both are supplied. 1900 to 2100. |
| `vehicle.first_registration` | string (date) | First registration date in YYYY-MM-DD format. The current valuation payload uses its year; do not derive a registration date from a photograph. At most 10 characters. |
| `vehicle.mileage` | object | Odometer value with an explicit unit. Values are converted to the requested market convention before scoring. |
| `vehicle.mileage.value` **required** | number | Non-negative odometer reading in the accompanying unit. Do not convert it twice when changing the unit. 0 to 10000000. |
| `vehicle.mileage.unit` **required** | string | Odometer unit: km means kilometres, mi means miles, and mil means Scandinavian miles of ten kilometres. One of `km`, `mi`, `mil`. |
| `vehicle.transmission` | string | Known transmission type, automatic or manual. Omit it when unknown; an omitted gearbox is not treated as manual. One of `manual`, `automatic`. |
| `vehicle.drive` | string | Driven wheels: fwd, rwd, awd or 4wd, or 2wd when only two-wheel drive is known (the value catalogue drivetrains return for most cars). Use the value supported by the vehicle specification. One of `fwd`, `rwd`, `2wd`, `awd`, `4wd`. |
| `vehicle.power_hp` | number | Engine or drivetrain power in horsepower. Convert a source value in kilowatts before submitting it here. 0 to 3000. |
| `vehicle.engine_size_l` | number | Combustion engine displacement in litres, such as 1.5. Omit for a fully electric vehicle. 0 to 30. |
| `vehicle.battery_kwh` | number | Known traction battery capacity in kilowatt-hours. Omit when the source does not report a capacity. 0 to 500. |
| `vehicle.electric_range_km` | number | Known electric driving range in kilometres, regardless of the odometer unit or valuation market. 0 to 3000. |
| `vehicle.doors` | integer | Number of doors reported by the vehicle specification. Helps distinguish otherwise similar body variants. 1 to 10. |
| `vehicle.seats` | integer | Number of seats reported by the vehicle specification. 1 to 20. |
| `vehicle.condition` | number | Known numeric vehicle condition grade from 0 through 4. Omit unknown condition rather than inventing a grade. 0 to 4. |
| `vehicle.drive_side` | string | Steering wheel position: left for left-hand drive and right for right-hand drive. This is not the side of the road used by traffic. One of `left`, `right`. |
| `vehicle.flags` | object | Boolean risk and eligibility attributes. Only the documented keys have an effect: when one is true, the vehicle is outside the market's model and the valuation is refused with unsupported_vehicle (some keys only in the markets they name). false has the same effect as leaving the key out. Any other key is ignored with a flags_not_recognized warning, and a market-specific key sent for another market is ignored with a flags_not_applicable warning. At most 30 entries. |
| `vehicle.flags.is_damaged` | boolean | The vehicle is damaged. When true the vehicle is refused with unsupported_vehicle in every market. |
| `vehicle.flags.has_new_engine` | boolean | The engine has been replaced. When true the vehicle is refused with unsupported_vehicle in every market. |
| `vehicle.flags.is_leasing_price` | boolean | The price is a leasing price, not a sale price. When true the vehicle is refused with unsupported_vehicle in every market. |
| `vehicle.flags.has_no_battery` | boolean | An electric vehicle sold without its traction battery, for example under battery rental. When true the vehicle is refused with unsupported_vehicle in every market. |
| `vehicle.flags.is_auction_car` | boolean | The vehicle is sold at auction. When true the vehicle is refused with unsupported_vehicle in every market. |
| `vehicle.flags.is_commercial_car` | boolean | The vehicle is registered or sold as a commercial vehicle. When true the vehicle is refused with unsupported_vehicle in every market. |
| `vehicle.flags.price_is_leasing_rate` | boolean | The price is a periodic leasing rate, not a sale price. When true the vehicle is refused with unsupported_vehicle in every market. |
| `vehicle.flags.has_no_tax` | boolean | The price excludes registration tax. Applies in DK, SE, DE, ES, AT and PT, where true is refused with unsupported_vehicle. |
| `vehicle.flags.has_yellow_plates` | boolean | Registered on Danish yellow (commercial) plates. Applies in DK only, where true is refused with unsupported_vehicle. |
| `vehicle.flags.is_camper_version` | boolean | A camper conversion. Applies in DK only, where true is refused with unsupported_vehicle. |
| `vehicle.equipment` | array | Known equipment as feature keys from /v1/catalogue/enums, such as `EXTERIOR_TOWBAR_FIXED` or `INFOTAINMENT_NAVIGATION`, as strings or as the items of a returned Vehicle. The earlier keys such as `has_tow_bar` are still accepted. Unrecognized keys produce a warning. At most 150 items. |
| `vehicle.vin` | string | Optional vehicle identification number; the same as `registration.vin`. Live keys look it up: in DK in the Danish Motor Register, elsewhere with VIN decoding (make, model and model year). Never looked up in DE, IT or ES, or with test keys. Looked-up values only fill attributes you leave out and are identified against the catalogue like your own; their provenance in `identification.fields` has source registry and a source_id. A value that disagrees with one you supplied gives a registry_conflict warning while yours is used. If the lookup cannot be used, your other attributes are used and a warning says why. Included in the request's credit. The raw VIN is not retained. At most 30 characters. |
| `vehicle.registration_plate` | string | Optional registration plate; the same as `registration.registration_plate`. Live keys look it up in the national register where one is connected (DK, the Danish Motor Register); elsewhere it gives a registry_lookup_not_available warning, and a vin sent with it is still decoded. Looked-up values only fill attributes you leave out, as for vin. The odometer reading of the last inspection is never used as the mileage. Included in the request's credit. The raw plate is not retained. At most 30 characters. |
| `vehicle.identity` | object | Canonical identity: a catalogue ID per level, or a brand and model name. Canonical form of `make`, `model`, `variant` and `catalogue`. |
| `vehicle.identity.level` | string | Read-only part of a returned Vehicle. Accepted and ignored. |
| `vehicle.identity.<level>` | object | An identity level: `brand`, `model`, `generation`, `drivetrain` or `equipment_variant`. Send an `id`, or a `name` for `brand` and `model`. |
| `vehicle.identity.<level>.id` | string or null | Catalogue ID from the catalogue API or a returned Vehicle. Wins over `name`. All IDs must describe one consistent catalogue hierarchy. |
| `vehicle.identity.<level>.name` | string | Name as your source spells it. Used for `brand` and `model` when there is no `id`; ignored at the other levels. At most 200 characters. |
| `vehicle.identity.<level>.from_year` | integer | Read-only part of a returned generation. Ignored. |
| `vehicle.identity.<level>.to_year` | integer | Read-only part of a returned generation. Ignored. |
| `vehicle.identity.variant_text` | string | Free-text engine, trim or version designation; the same as `variant`. At most 200 characters. |
| `vehicle.specs` | object | Canonical technical facts: `energy.fuel` for `fuel`, `power.hp` or `power.kw` for `power_hp`, `transmission.type` for `transmission`, `traction` for `drive`, and `body`, `doors`, `seats`, `engine_size_l`, `battery_kwh` and `electric_range_km` as named. |
| `vehicle.specs.body` | string | Body type. One of `hatchback`, `estate`, `suv`, `sedan`, `mpv`, `convertible`, `coupe`. |
| `vehicle.specs.doors` | integer | Number of doors. 1 to 10. |
| `vehicle.specs.seats` | integer | Number of seats. 1 to 20. |
| `vehicle.specs.energy` | object | Energy source. |
| `vehicle.specs.energy.fuel` | string | Fuel or electrification type, from the public vocabulary of /v1/catalogue/enums. One of `petrol`, `diesel`, `electric`, `hybrid`, `plug_in_hybrid_petrol`, `plug_in_hybrid_diesel`, `lpg`, `cng`, `ethanol`, `hydrogen`. |
| `vehicle.specs.power` | object | Engine or drivetrain power. Returned in both units; on input `hp` wins over `kw`. |
| `vehicle.specs.power.hp` | number | Power in horsepower. 0 to 3000. |
| `vehicle.specs.power.kw` | number | Power in kilowatts, rounded. On input it is converted to horsepower (1 kW = 1.35962 hp) when `hp` is absent. 0 to 2300. |
| `vehicle.specs.engine_size_l` | number | Combustion engine displacement in litres, such as 1.5. 0 to 30. |
| `vehicle.specs.transmission` | object | Gearbox. Absent when unknown; absent does not mean manual. |
| `vehicle.specs.transmission.type` | string | Gearbox type. One of `manual`, `automatic`. |
| `vehicle.specs.traction` | string | Driven wheels. `2wd` means two-wheel drive with the driven axle not recorded, which is what the catalogue knows for most cars. One of `fwd`, `rwd`, `2wd`, `awd`, `4wd`. |
| `vehicle.specs.battery_kwh` | number | Traction battery capacity in kilowatt-hours. 0 to 500. |
| `vehicle.specs.electric_range_km` | number | Electric driving range in kilometres. 0 to 3000. |
| `vehicle.registration` | object | Canonical registration facts and identifiers. A VIN, plate or HSN/TSN pair is looked up as described for `vin`. |
| `vehicle.registration.country` | string | Read-only part of a returned Vehicle. Ignored: the request's `country` is the market. At most 10 characters. |
| `vehicle.registration.first_registration` | string (date) | First registration date (YYYY-MM-DD); the same as `first_registration`. At most 10 characters. |
| `vehicle.registration.model_year` | integer | Model or registration year; the same as `model_year`. 1900 to 2100. |
| `vehicle.registration.vin` | string | Vehicle identification number; the same as `vin`. At most 30 characters. |
| `vehicle.registration.registration_plate` | string | Registration plate; the same as `registration_plate`. At most 30 characters. |
| `vehicle.registration.hsn` | string | German manufacturer code (HSN, field 2.1 of the registration document). Looked up with `tsn` in the Kraftfahrt-Bundesamt type snapshot. At most 8 characters. |
| `vehicle.registration.tsn` | string | The first three characters of the German type code (TSN, field 2.2). Looked up with `hsn`. At most 8 characters. |
| `vehicle.registration.original_market` | string | The car's original sales market (ISO 3166-1 alpha-2), only when you know it independently. Used when a VIN is decoded. At most 10 characters. |
| `vehicle.registration.production_year` | integer | Read-only part of a returned Vehicle. Ignored. |
| `vehicle.listing` | object | Canonical facts about this particular car: `mileage`, `colour.name` for `color`, `condition.grade` for `condition`, `drive_side` and `flags`. |
| `vehicle.listing.mileage` | object | Odometer reading; the same as `mileage`. |
| `vehicle.listing.mileage.value` **required** | number | Non-negative odometer reading in the accompanying unit. 0 to 10000000. |
| `vehicle.listing.mileage.unit` **required** | string | Odometer unit: km, mi or mil (Scandinavian mile, 10 km). One of `km`, `mi`, `mil`. |
| `vehicle.listing.mileage.read_on` | string (date) | Read-only date of a register's reading. Ignored. A register's past inspection reading is not today's mileage: replace it before you value the car. |
| `vehicle.listing.colour` | object | Exterior colour. |
| `vehicle.listing.colour.name` **required** | string | Colour from your source; the same as `color`. At most 200 characters. |
| `vehicle.listing.colour.family` | string | Read-only part of a returned Vehicle. Accepted and ignored. At most 100 characters. |
| `vehicle.listing.condition` | object | Condition. |
| `vehicle.listing.condition.grade` **required** | number | Condition grade from 0 through 4; the same as `condition`. 0 to 4. |
| `vehicle.listing.drive_side` | string | Steering wheel position; the same as `drive_side`. One of `left`, `right`. |
| `vehicle.listing.flags` | object | Boolean risk and eligibility attributes; the same keys and effect as `flags`. At most 30 entries. |
| `vehicle.object` | string | Read-only part of a returned Vehicle. Accepted and ignored. |
| `vehicle.status` | string | Read-only part of a returned Vehicle. Accepted and ignored. |
| `vehicle.catalogue_version` | string | Read-only part of a returned Vehicle. Accepted and ignored. |
| `vehicle.fields` | object | Read-only part of a returned Vehicle. Accepted and ignored. |
| `vehicle.candidates` | object | Read-only part of a returned Vehicle. Accepted and ignored. |
| `description` | string | Unstructured listing text describing the vehicle. Existing parsers and deployment-configured optional AI can propose attributes; the response identifies assumptions and unresolved inputs. 1 to 20000 characters. |
| `images` | array | Up to eight vehicle photos, each supplied by HTTPS URL or inline base64 data. AI image resolution is deployment-configured and never runs for test keys. Warnings identify unused images. On a live key, photos cost one extra credit per request (not per photo), charged only when the request succeeds and a value was read from them (`usage.charges.images`); skipped or unused photos are not charged. At most 8 items. |
| `images[].url` | string (uri) | Public HTTPS image URL on port 443, without credentials or fragments. Private network destinations and redirects are rejected. Remote images must be supported image types and at most 8 MB each. At most 2048 characters. |
| `images[].data` | string | Strict base64-encoded image bytes, without a data-URL prefix. Inline data must also fit the total 1 MB API request limit. At most 1000000 characters. |
| `images[].media_type` | string | MIME type for inline image bytes: image/jpeg, image/png, image/webp or image/gif. The actual image signature is checked. At most 100 characters. |
| `pricing` | object | The asking-price context for this valuation. The result explicitly states its currency and whether the expected asking price is dealer retail or private sale. |
| `pricing.price_basis` | string | dealer_retail estimates a freshly listed dealer asking price; private_sale estimates a private seller asking price. These are not guaranteed transaction or trade-in prices. One of `dealer_retail`, `private_sale`. |
| `pricing.seller_region` | string | Known seller region within the selected market. This is passed as regional pricing context when available. At most 120 characters. |
| `pricing.asking_price` | number | Optional asking price in the market currency. Used to calculate AutoUncle price ratings and rating stability across the uncertainty interval. 0 to 100000000. |
| `options` | object | Resolution and minimum precision controls. Missing optional values use the documented default behaviour. |
| `options.resolution` | string | auto uses deterministic resolution and optional configured AI; no_ai uses deterministic resolution only; strict disables AI and refuses missing registration year or mileage. Mileage is never assumed without allow_mileage_estimation=true, and strict mode overrides that permission. Configured live AI is invoked only for missing identity/year or core drivetrain attributes, catalogue candidates the deterministic matcher cannot separate, equipment or condition the request does not supply, and whenever images are sent (for the equipment, colour, condition and drive side they show). An image that cannot be read is skipped with an image_skipped warning. Once invoked, a dependency timeout or outage fails the valuation; it is never silently treated as successful enrichment. One of `auto`, `no_ai`, `strict`. |
| `options.min_precision` | string | Minimum acceptable precision grade. If the result falls below this grade, the request is refused without consuming a credit. Sandbox results are indicative. One of `high`, `medium`, `low`, `indicative`. |
| `options.include` | array | Optional response sections to add. A section never changes the price, intervals or precision. `comparables` adds up to five comparable listings on sale and five recently sold in the same market, with top-level facts only, as supporting evidence for the valuation (see `comparables` in the response). One extra credit on a live key, charged only when listings are returned (`comparables.status` `included`) and released otherwise. Unavailable in Denmark, where the response says so with a note instead. `trade_in_price` adds AutoUncle's estimate of a fair trade-in price with a range (see `trade_in_price` in the response). One extra credit on a live key, charged only when it is returned (`trade_in_price.status` `included`). Available in AT, CH, DE, DK, ES, FR, GB, IT, NL, PL, PT and SE; in other markets the response says so with a note and nothing is charged. `similar_cars_link` adds `similar_cars_url`, a link to similar cars for sale on the market's AutoUncle site. Free, in every market. At most 10 items. |
| `options.allow_mileage_estimation` | boolean | Explicitly allow a fixed 96,000 km baseline when mileage cannot be extracted or supplied. This is an assumption, not a vehicle-specific estimate; it lowers precision. Default false. Strict resolution still refuses missing mileage. Default `false`. |
| `options.allow_equipment_estimation` | boolean | Explicitly allow equipment the request does not state to be assumed: the catalogue's equipment for the identified trim when the catalogue lists it, otherwise the equipment at least 70% of comparable vehicles on the market have. Assumed equipment is only added, never against equipment the request, its description or its photos state or deny, and is marked source imputed, basis assumed in identification.fields (availability unknown in vehicle.equipment), with an equipment_assumed warning and an improve_precision hint. Like any assumption it lowers precision to low. Test keys use only the catalogue trim, never market data. Default false. Strict resolution ignores it. Default `false`. |

## The returned vehicle

A `valued` result returns the [Vehicle](/docs/reference/vehicles#the-vehicle-object) that was priced, with its [identification](/docs/reference/vehicles#identification) beside it:

```json
{
  "vehicle": {
    "avs": { "version": "0.3", "kind": "vehicle" },
    "identity": {
      "brand": { "name": "VW", "ids": [{ "scheme": "autouncle", "value": "b-0957579dc5bca6de229d2f32" }] },
      "model": { "name": "Golf", "ids": [{ "scheme": "autouncle", "value": "cm-6bb52590daf6d1b19108ec93" }] },
      "body": { "name": "Golf VIII", "ids": [{ "scheme": "autouncle", "value": "mg-40c5d8de40bb48ae60fc0a6c" }], "fromYear": 2019 },
      "drivetrain": { "name": "1.5 TSI (130 Hp)", "ids": [{ "scheme": "autouncle", "value": "dv-947a3199394a5a4b41cb2869" }] }
    },
    "specification": {
      "powertrain": { "energy": ["petrol"], "engine": { "displacementCc": 1500 }, "powerKw": 96, "powerHp": 130,
                      "transmission": { "type": "manual" }, "traction": "2wd" }
    },
    "vehicle": {
      "registration": { "country": "DK", "modelYear": 2021 },
      "odometer": { "km": 45000 }
    }
  },
  "identification": {
    "status": "identified",
    "level": "drivetrain",
    "catalogue_version": "5.6.9:NEW",
    "fields": {
      "/identity/brand": { "basis": "catalogue", "source": "catalogue_derived", "status": "derived" },
      "/identity/drivetrain": { "basis": "observed", "source": "catalogue_id", "status": "supplied" },
      "/specification/powertrain/powerHp": { "basis": "catalogue", "source": "catalogue_derived", "status": "derived" },
      "/vehicle/odometer": { "basis": "observed", "source": "provided", "status": "supplied" },
      "/vehicle/registration/modelYear": { "basis": "observed", "source": "provided", "status": "supplied" }
    }
  }
}
```

The example's `fields` are shortened.

- **Identity.** `identity.brand` and `identity.model` are always there; `identity.body` (AutoUncle's generation, which includes the body), `identity.drivetrain` and `equipment.trim` (the equipment variant) are present only when they were identified. Each carries its catalogue ID in `ids` (scheme `autouncle`) and its `name`. Store the IDs and send them back next time. A level that several catalogue records fit is left out of `identity` and listed in `identification.candidates`, and `identification.status` is `ambiguous`; the valuation still runs on the levels that are known, and a warning such as `drivetrain_ambiguous` tells you to pin the level.
- **Specification.** With an identified drivetrain, the catalogue's values; a value you sent that contradicts it has status `conflict` in `identification.fields`, with yours in `supplied`.
- **Provenance.** `identification.fields`, keyed by JSON Pointer into `vehicle`, says, per value, how it was established: `source` (`catalogue_id`, `catalogue_derived`, `catalogue_match`, `provided`, `registry`, `text_parser`, `ai_text`, `ai_vision`, `imputed` or `default`), `basis` (`observed`, `extracted`, `catalogue` or `assumed`; see [field provenance basis](/docs/notices#field-provenance-basis)) and `status`. A mileage baseline or other default has status `assumed`.

The matched model can be a catalogue alias of the model you named. For example, `make: "Volkswagen", model: "Golf", model_year: 2020` may identify the model `Golf VII` (`cm-88dbede1978bc412872a6e1c`) rather than `Golf` (`cm-6bb52590daf6d1b19108ec93`). Both are valid catalogue IDs.

`precision.identity_level` names the most specific level that was identified. You can post the returned `vehicle` back unchanged in a later request, for example to value the same car again with a new mileage.

See the [valuation result reference](/docs/reference/valuations#the-valuation-result) for every field.