# Improve precision with hints

Every valued result tells you what would make it more precise. This guide shows how to read those hints, act on them automatically or with the user, and set a minimum precision you are willing to accept.

## Where precision comes from

Two things limit how precise a valuation can be:

1. **How well the vehicle is identified.** A pinned drivetrain is far more specific than "VW Golf". `precision.identity_level` tells you the most specific level that was resolved.
2. **What is known about this particular car.** Actual mileage, registration year, condition and equipment all matter. Assumed values are flagged.

`precision.grade` (`high`, `medium`, `low`, `indicative`) combines both with the model's own uncertainty. The [precision page](/docs/precision) explains grades and intervals in detail.

## Read the three signals

| Field | Tells you | Example |
| --- | --- | --- |
| `improve_precision[]` | What to send next time, most useful first, with a qualitative `expected_impact` | `vehicle.catalogue.drivetrain_id`, reason `drivetrain_unresolved`, impact `high` |
| `warnings[]` | What was wrong or uncertain in this request | `generation_ambiguous`, `year_imputed`, `equipment_not_recognized` |
| `identification.fields` | Where each value came from; `status: assumed` marks a value that was assumed, not supplied | `/vehicle/odometer` with source `imputed` and status `assumed` |
| `identification.candidates` | Catalogue records that fit when a generation or drivetrain is ambiguous | Two drivetrains of the Golf VIII with the power you sent |

A typical first result for "VW Golf, 2020, 60,000 km":

```json
{
  "improve_precision": [
    { "field": "vehicle.catalogue.drivetrain_id", "reason": "drivetrain_unresolved", "expected_impact": "high",
      "message": "Select the exact engine and transmission from the catalogue." },
    { "field": "vehicle.condition", "reason": "condition_unknown", "expected_impact": "medium",
      "message": "Provide the vehicle's condition." }
  ],
  "warnings": [
    { "code": "generation_ambiguous",
      "message": "More than one generation fits the supplied information. Select its catalogue ID for greater precision." }
  ]
}
```

`expected_impact` is qualitative. It does not promise that the price will move, or the interval narrow, by a fixed amount.

## Act on common hints

| `reason` | Field | What to do |
| --- | --- | --- |
| `drivetrain_unresolved` | `vehicle.catalogue.drivetrain_id` | Let the user pick the drivetrain, or send `variant`, `fuel`, `transmission` and `power_hp` so it can be matched. See [build a catalogue picker](/docs/guides/catalogue-picker). |
| `condition_unknown` | `vehicle.condition` | Send a numeric condition grade from 0 to 4 if your source has one. Do not invent it. |
| `imputed` | for example `model_year` or `mileage` | A value was assumed. Ask for the actual value. |
| `equipment_assumed` | `vehicle.equipment` | Equipment was assumed (`options.allow_equipment_estimation`). Ask which equipment the car has, and send it in `vehicle.equipment`. |
| `ai_interpreted` | the interpreted field | A value was read from text or photos by AI. Ask the user to confirm it, then send it as a structured field. See [free text and photos](/docs/guides/text-and-photos). |

When a hint carries `candidates`, they are catalogue identities to choose from. Show their `name` and send the chosen `id`.

Match on `reason` and `field`, and show `message` to users. New reasons can appear; treat an unknown reason by showing its message.

## Common warnings

| `code` | Meaning | Fix |
| --- | --- | --- |
| `generation_ambiguous` | Several generations fit; the valuation used the best match, and `identification.candidates.generation` lists them | Send `generation_id` or `drivetrain_id`, or the first registration date |
| `year_imputed` | The registration year was assumed | Send `model_year` or `first_registration` |
| `km_imputed` | The fixed mileage baseline was used | Send actual `mileage` |
| `equipment_assumed` | Equipment was assumed from the catalogue trim or from similar vehicles | Send the fitted equipment in `vehicle.equipment` |
| `assumed_equipment_ignored` | A posted-back Vehicle listed equipment its `fields` mark as assumed; it was not used as stated equipment | Send only equipment the car is known to have |
| `equipment_not_assumed` | Equipment assumption was requested, but nothing could be assumed (or `strict` was used) | Send the equipment, or accept the result without it |
| `equipment_not_recognized` | Some `equipment` keys are not known | Use keys from [/v1/catalogue/enums](/docs/reference/catalogue#get-v1-catalogue-enums) |
| `catalogue_candidate_conflict` | An inferred candidate contradicted the catalogue IDs you sent and was ignored | Check that your IDs and attributes describe the same vehicle |
| `images_not_used` | Photos added nothing usable | Send structured attributes or a description |
| `image_skipped` | An image could not be read and was skipped; the message names it | Send JPEG, PNG, WebP or GIF from a public HTTPS URL without redirects |

## A two-step flow that works

1. **Value with what you have.** Show the price, the 80% interval and the grade, plus the top one or two `improve_precision` messages.
2. **Ask for the high-impact details.** Typically the drivetrain and actual mileage.
3. **Value again with a new idempotency key.** The new request has a different body, so it needs a new key.

Each live valuation that succeeds uses a credit, so ask for the details before valuing when you can. Catalogue lookups for the picker are free.

## Set a minimum precision

When a result below a certain grade is useless to you, say so up front with `options.min_precision`:

```json
{
  "country": "DK",
  "vehicle": {
    "make": "VW",
    "model": "Golf",
    "model_year": 2020,
    "mileage": { "value": 60000, "unit": "km" }
  },
  "options": { "min_precision": "medium" }
}
```

If the result would fall below `medium`, the request is refused with `422` [`precision_below_minimum`](/docs/errors#precision_below_minimum) and **no credit is used**. The refusal's `fix` tells you what to add. Grades are ordered `high` > `medium` > `low` > `indicative`.

> **Note:** Test results are always `indicative`, so any `min_precision` above `indicative` is refused in test mode. Use `"min_precision": "indicative"` (or omit it) in tests, and test the refusal path on purpose with a higher value.

## Pitfalls

- **Treating hints as errors.** A result with hints is still a valid valuation. Hints are suggestions.
- **Filling hints with guesses.** Sending an invented condition grade to make a hint disappear makes the result less accurate, not more.
- **Re-valuing in a loop.** Ask once for the missing details, then value again. Do not loop automatically on hints.

## Next steps

- [Precision & intervals](/docs/precision) to present the result.
- [Refusals & missing mileage](/docs/guides/refusals-and-mileage).
- [The vehicle object](/docs/concepts/vehicle).