# Notes and data sources

This page explains the two arrays that accompany every result, `notes` and `attributions`, and the provenance basis of each value. Every valuation, catalogue and account result, over REST and MCP, carries two arrays: `notes` and `attributions`. Both are always present and never truncated. Keep them with the result wherever you show or store it.

Each kind of information has its own place in a result:

| What | Where |
|---|---|
| How each value was established | `identification.fields` (`source`, `basis`, `status`) |
| Uncertainty and problems with this request's input | `precision`, `warnings[]`, `improve_precision[]` |
| Operational failures | `status` and `error` |
| Standing limitations, disclaimers and legal notices | `notes[]` |
| Which data sources contributed, and under which licence | `attributions[]` |

## Notes

```json
{
  "code": "market_specific",
  "category": "limitation",
  "message": "This result applies only to the DK market, its currency and the stated price basis. Do not apply it to another market.",
  "pointers": ["/valuation", "/price_ratings"],
  "source_ids": []
}
```

`category` is `disclaimer` (how the result may be relied on), `limitation` (where it does not apply or is weaker) or `legal_notice` (wording a data source requires you to show). Match on `code`. `pointers` are JSON Pointers into the same result; an empty array means the note applies to the whole result.

Current valuation notes include `estimate_not_offer`, `market_specific`, `synthetic_result` for test-mode results and `automated_interpretation` when attributes were interpreted from text or photos, or a catalogue level was chosen from the description. With [comparable listings](/docs/valuations#comparable-listings) requested, `comparables_are_evidence` (a disclaimer: the listings support the price but are not its basis, and their prices are asking prices) accompanies included listings, and `comparables_unavailable_in_market` (a limitation) explains why a market such as Denmark returns none. A requested [trade-in price](/docs/valuations#trade-in-price) adds `trade_in_price_is_estimate` (a disclaimer: an estimate, not an offer) when it is returned, or `trade_in_price_unavailable_in_market` (a limitation) in a market without one. A [selling-time forecast](/docs/selling-time) adds `selling_time_is_forecast`. A [market & demand](/docs/reference/market) result carries `market_figures_describe_listings` (a disclaimer: aggregates over the listings AutoUncle tracks, not registrations or confirmed sales; left the market is not always a sale).

Note fields:

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | Stable machine-readable note code. Match on code, not message. Pattern `^[a-z][a-z0-9_]*$`. |
| `category` | string | disclaimer: how the result may be relied on; limitation: where the result does not apply or is weaker; legal_notice: verified wording a data source requires to be shown. One of `disclaimer`, `limitation`, `legal_notice`. |
| `message` | string | Plain-language text of the note, suitable for display next to the result. |
| `pointers` | array | Parts of the result the note applies to; empty when it applies to the whole result. |
| `source_ids` | array | Attributed sources that caused the note; empty for general notes. |

## Attributions

```json
{
  "source_id": "autouncle_vehicle_catalogue",
  "name": "AutoUncle vehicle catalogue",
  "url": "https://data-services.autouncle.com/docs/catalogue",
  "party": "first_party",
  "role": "vehicle_catalogue",
  "license": { "id": "autouncle_data_services_terms", "name": "AutoUncle Data Services terms", "url": "https://data-services.autouncle.com/legal/terms" },
  "attribution_text": null,
  "notice_status": "pending_review",
  "notice_version": "autouncle_vehicle_catalogue@1",
  "pointers": ["/vehicle/identity/brand", "/vehicle/identity/model"]
}
```

- Only sources that actually contributed to this result are listed. Being enabled for your account is not enough.
- `pointers` shows which parts of the result each source contributed to.
- When `attribution_text` is present, display it wherever you show or redistribute the contributing data. Do not shorten or drop it.
- `notice_status: pending_review` means licence and attribution obligations have not been verified yet. Do not assume that none apply. `license` is null when no licence reference has been published yet.
- `source_id` is stable. `notice_version` identifies the registry revision used for the result.

Attribution fields:

| Field | Type | Description |
| --- | --- | --- |
| `source_id` | string | Stable source identifier. Safe to store and compare. Pattern `^[a-z][a-z0-9_]*$`. |
| `name` | string | Public source name. |
| `url` | string or null | Public page describing the source, when one exists. |
| `party` | string | first_party: AutoUncle's own data or models; third_party: an external provider or dataset. One of `first_party`, `third_party`. |
| `role` | string | What the source contributed: `vehicle_catalogue`, `valuation_model`, `ai_interpretation`, `vehicle_registry`, `market_listings` or `selling_time_model`. One of `vehicle_catalogue`, `valuation_model`, `ai_interpretation`, `vehicle_registry`, `market_listings`, `selling_time_model`. |
| `license` | any | Licence or terms governing this source's contribution, or null when not yet verified. |
| `attribution_text` | string or null | Attribution wording you must display wherever you show or redistribute the contributing data. Null when none is required or when the wording is still pending review; never drop or shorten it when present. |
| `notice_status` | string | verified: licence and wording checked against an authoritative source. pending_review: obligations are not yet verified; do not infer that none apply. One of `verified`, `pending_review`. |
| `notice_version` | string | Registry revision in force when the result was produced. Stored read-backs and idempotent replays keep this snapshot. Pattern `^[a-z][a-z0-9_]*@[0-9]+$`. |
| `pointers` | array | Parts of the result this source contributed to. |

To display them correctly in your product, see [show notes & attributions](/docs/guides/notes-and-attributions).

## Empty arrays

An empty `attributions` array means the result contains no source data. This applies to refusals, failures and metadata such as enums, countries, catalogue version and account details. An empty `notes` array means no standing limitation applies beyond this documentation.

Synthetic test-mode valuations never cite the valuation model. They carry a `synthetic_result` note. Catalogue identities they resolved are still attributed to the catalogue.

## Stored results and retries

Notes and attributions are stored with the result. `GET /v1/valuations/{id}`, `get_valuation` and idempotent replays return the notices that applied when the valuation was produced, even if a source's notice changes later. Results recorded before notices existed get notices reconstructed from their recorded provenance, marked with a `notices_reconstructed` note.

## Field provenance basis

Every entry in `identification.fields` has a `basis`:

| basis | Meaning | Sources |
|---|---|---|
| `observed` | You supplied it, or it was read from a registry record | `provided`, `catalogue_id`, `registry` |
| `extracted` | Read from the text or photos you supplied, by rules or AI | `text_parser`, `ai_text`, `ai_vision` |
| `catalogue` | Derived from, or matched against, the AutoUncle catalogue | `catalogue_derived`, `catalogue_match` |
| `assumed` | A heuristic default or fixed baseline, not evidence about this vehicle | `imputed`, `default` |

Values interpreted by AI are never labelled `imputed`. Their improvement hint has reason `ai_interpreted` and asks you to confirm the value. Assumptions keep reason `imputed` and ask for the actual value.

When several catalogue generations or drivetrains fit equally well and the description decided between them, the chosen level's entry keeps source `catalogue_match` and basis `catalogue` (the record is catalogue data) and adds `selected_by: "ai_text"`. Because an automated interpretation made that choice, the level is also listed under the `automated_interpretation` note and the automated interpretation attribution.