---
title: "Data dictionary"
description: "Search card and auction detail field lists, the normalized `vehicle_details` block, per-source coverage, and what is never exposed."
canonical: "https://thecarapi.com/docs/schema"
contract_version: "2026-08-19"
api_base: "https://api.thecarapi.com"
source: "https://thecarapi.com/docs/schema.md"
---

# Data dictionary

Search card and auction detail field lists, the normalized `vehicle_details` block, per-source coverage, and what is never exposed.

## Search result card fields

Fields are returned when the selected source provides them.

```text
auction_id, site_name, auction_batch_id, batch_start_date, batch_end_date,
auction_sec_left, buy_now_price, car_country_extended, country_code,
country_marker_code, country_marker_name, country_marker_color, car_name_en,
current_price, buynow_final, current_final, buynow_bgn, current_bgn,
date_first_registration, has_technical_damage, is_broken, is_buy_now, kw,
mileage, start_price, final_price, thumbnail_url, hp, pk, size, picture_count,
clean_make, clean_model, model_display, model_class_series, fuel_group,
gearbox_group, registration_year, public_damage_state, public_price_eur,
offer_link, is_active, is_top_offer, top_offer_savings_pct, top_offer_savings
```

## Additional auction detail fields

```text
car_id, chassis_number, co2, buynow_tax, current_tax, buynow_tax_delivery,
current_tax_delivery, cylinder_capacity, effluent_standard_group_search,
is_margin, requested_sales_price, special_price, places, seller_score,
country_code_dealer, community_name, community_seller_name, currency_code_id,
vehicle_grade_id, mechanical_indicator_id, is_commercial_car, car_identification,
car_report_types, images, gallery_images, created_at, updated_at, first_seen_at,
last_seen_at, last_available_at, last_changed_at, vehicle_details, vault_gallery,
co2, co2_estimated, co2_estimated_standard, estimated_value_eur, steering
```

> **The fields worth knowing first** — `public_price_eur` is the canonical public EUR price. `car_identification` is a source-specific specification map. `auction_end_at` is the absolute UTC close instant — drive countdowns from it, not from `batch_end_date` (per-house timezone) or `auction_sec_left` (a snapshot taken at the last refresh, not seconds from now). `estimated_value_eur` is the auction house's own valuation and **not a price you can pay** — see [Fields by source](https://thecarapi.com/docs/fields-by-source). `co2` and `co2_estimated` are measured and derived respectively and must never be merged — see [CO2 & emissions](https://thecarapi.com/docs/co2).

## The vehicle_details block

Present on `/api/auction/{site}/{id}` and `/api/car-details`. The three detail-rich sources describe the same concepts under different names — a downloadable file is `Documents[]` on Auto1 but `ECarsTradeDocuments[]` on eCarsTrade, while `Documents` on OpenLane is a dict of paperwork booleans and not a file list at all — so this block normalizes them. Read it instead of branching on `site_name`. Every key is omitted when the source has nothing for it, and the whole block is omitted while `details_pending` is true.

| Key | Type | Meaning |
| --- | --- | --- |
| `documents` | array | Downloadable files: `{type, url, label}`. Links only. |
| `inspection_reports` | array | Inspection/damage/appraisal reports: `{type, type_id, url}`. |
| `option_reports` | array | Equipment reports (`type_id` 4), kept separate from damages. |
| `car_reports` | array | OpenLane's own report index, as the source sends it. |
| `service_history` | array | Per-visit rows: `{date, mileage_km, company, description, price_eur}`. |
| `service_history_summary` | object | Whether serviced, last date, last mileage. |
| `technical_inspection` | object / string | Roadworthiness inspection validity. |
| `paperwork` | object | `COCAvailable`, `RegistrationDocsAvailable`, `IsV5Present`, `LicensePlate`. |
| `condition` | object | Driveability, keys, tyre depths, grade, inspection status, accident flag. |
| `damages` | array | Structured damage records per panel/area, where the source provides them. |
| `damage_comment` | string | Free-text damage notes (also `damage_service_comment`). |
| `technical_issues` / `remarks` | string | eCarsTrade's free-text defect and remark text. |
| `is_damaged` / `has_technical_issues` | boolean | eCarsTrade category flags. |
| `estimated_repair_costs` | number | Estimated cost to repair the vehicle's damage. Not a fee. |
| `paint_measurements` / `wheels` / `highlights` | array / object | Auto1 condition extras. |
| `equipment` | array | Equipment/options list. |
| `warranty` | object | Warranty type, expiry date and mileage. |
| `specs` | object | Engine, body, dimensions, emissions, EV charging figures. |
| `location` | object | Physical and origin country of the vehicle. |
| `seller` | object | Seller/dealer record as the source provides it. |

### Coverage is not uniform across sources

Each auction house publishes a different subset of these keys, and the differences are large: only eCarsTrade has per-visit service rows, only Auto1 has paint measurements, and OpenLane publishes no document files at all. This is an upstream limitation, not a gap in our data — do not build a UI that assumes a key is always there. The full coverage matrix, the OpenLane report-type codes and the per-source traps live on [Fields by source](https://thecarapi.com/docs/fields-by-source).

## Never exposed

Bidder and private fields — bidder identities, private bids, personal maximums, and order data — are never returned. Neither is account-scoped commercial data: the auction houses' fee, cost and delivery figures are quoted to *our* buyer account and *our* delivery address, so they describe our commercial terms rather than the vehicle.

| Removed | Examples |
| --- | --- |
| Fees and auction terms | `Fees`, `bidprice`, `MerchantVat`, `Finance`, `Bidding`, `PackageDeal`, `commission_tiers`, `price_breakdown` |
| Delivery quoted to our address | Every key beginning `delivery` or `selfpickup`, at any depth, plus `transport`, `TransportOptions`, `StandingFees`, `PickupAddress`, `CompoundAddress` |
| Third-party contact details | Email addresses redacted from free-text values; surrounding text kept |
| Our identity on the platforms | The buyer-account identity each source sees, our logistics account references, and `BidHistory` |
| Internal processing metadata | `_metrics`, `details_fetch_meta`, `enrich_errors` |

Still served: the auction house's own published asking prices (`price_buy_now`, `price_min_bid`, `price_estimation`), the VAT scheme (`is_margin`, `vat_scheme`), the estimated repair cost, `Specs.TransportCategoryId` (a vehicle class, not a shipment), the seller/warehouse location, and `buynow_tax_delivery` / `current_tax_delivery`. For landed-cost figures use the [import calculator](https://thecarapi.com/docs/calculator), which is built for your own route.

## Sources and enums

| Type | Values |
| --- | --- |
| Sources | `schadeautos`, `auto1`, `openlane`, `copart`, `encar`, `ecarstrade`, `japanauction` |
| Sort | `default`, `random`, `newest`, `top_offers`, `time_left_least`, `time_left_desc`, `time_left_most`, `price_low`, `price_high`, `year_new`, `year_old`, `brand_az`, `brand_za` |
| `vehicle_type` | `cars`, `suvs & trucks` (alias: `suvs and trucks`) |
| `smart_filter` | `top_offers`, `low_mileage`, `best_value` |
| Booleans | `true`, `false`, `1`, `0`, `yes`, `no` |

The European classifieds network is not in the source list. It is retail market-reference data, not auction inventory, so it is not a valid `site` value — see the [classifieds endpoint group](https://thecarapi.com/docs/theparking) instead.