VinViewPro Integration Guide

Follow along to understand how we recommend you use our fitted options and valuation endpoints to create your expereinces.

Six calls, two products, two API keys. Part A identifies a car from its VIN in the JATO catalogue and pulls its fitted options and standard equipment. Part B values the same car, which needs an AutoGrab catalogue id and, for NL, one bridging search to get it.

Before you start

Item	Value	Notes
Host	https://api-v2.eu.autograb.com	All NL calls, both products.
Region	region=nl	Query parameter on GETs, body field on POSTs.
Auth	ApiKey: <key> header	Keys are per product, see below.
Fitted-options key	<EU_FITTED_KEY>	Licensed for catalogue=jato and /v2/vehicles/fitted_options
Valuation key	<NL_MARKET_KEY>	Licensed for /v2/valuations/predict (with bounds), /v2/vehicles search and registrations.
Transport	HTTP/1.1	The hosts negotiate HTTP/2; long fitted-options calls intermittently failed with curl: (16) Error in the HTTP2 framing layer. Force 1.1 (--http1.1).
Timeouts	Up to several minutes	Fitted-options reports usually return in 3–10 s but can legitimately run for minutes. Use a 300 s ceiling and surface a retry.
Errors	{"error": true, "message": "…"}	The text is in message; error is a boolean. 401 No active contracts means the key lacks that product for that region. 5xx is transient: retry.

Worked example throughout: VIN TMBER7NW7M3085070, a 2021 Skoda Scala Style, manual, petrol.

Part A · Fitted options report

1. Identify the vehicle in the JATO catalogue

Fitted options are keyed to JATO, so this lookup must carry catalogue=jato and use the fitted-options key. It returns the JATO vehicle id you pass to step 2, plus the full specification and a match confidence.

curl -sS --http1.1 --max-time 300 \
  -H "ApiKey: <EU_FITTED_KEY>" \
  "https://api-v2.eu.autograb.com/v2/vehicles/vins/TMBER7NW7M3085070?catalogue=jato&region=nl"

// 200
{
  "success": true,
  "vehicle": {
    "id": "<jato-vehicle-id>",          // pass verbatim to step 2
    "title": "2021 Skoda Scala Style Manual",
    "year": "2021", "make": "Skoda", "model": "Scala", "badge": "Style",
    "body_type": "Hatchback", "transmission": "Manual", "fuel": "Petrol",
    "drive_type": "Front Wheel Drive", "power_kw": 81,
    "num_doors": 5, "num_seats": 5, "capacity_cc": 999, ...
  },
  "confidence": "standard",                // or "reduced"
  "colour": "…"
}

Confidence. reduced means the VIN did not resolve to a single catalogue vehicle with enough certainty. The report in step 2 will still run, but its options may belong to the wrong variant. Production integrations should let the user correct the match (pick the variant from make/model/badge lists) before trusting the report; at minimum, flag it.

2. Request the fitted options report

POST the JATO id back with the VIN. Two optional fields are worth using: features: ["standard_equipment"] adds the factory-standard equipment list (typically 100–150 rows if you are entitled to this feature), and language adds Dutch text alongside the English.

curl -sS --http1.1 --max-time 300 -X POST \
  -H "ApiKey: <EU_FITTED_KEY>" -H "Content-Type: application/json" \
  --data '{
    "vehicle_id": "<jato-vehicle-id>",
    "vin": "TMBER7NW7M3085070",
    "region": "nl",
    "catalogue": "jato",
    "features": ["standard_equipment"],
    "language": "nl"
  }' \
  "https://api-v2.eu.autograb.com/v2/vehicles/fitted_options"

// 200 — for this VIN: 10 options, MSRP total €2,830, build date 2021-01-27
{
  "success": true,
  "build_date": "2021-01-27",
  "fitted_options": [
    {
      "option_id": "…",
      "option_type": "option",                 // option | pack | colour
      "option_code": "PW0",
      "option_title": "Full LED koplampen met cornering",
      "option_details": ["LED low beam LED high beam headlights", "Cornering lights/curb illumination", ...],
      "option_local_details": ["…"],           // only when language was sent
      "match_category": "Matched",
      "match_score": 1,                         // 0–1
      "msrp": 890,
      "build_sheet_lines": ["…"]
    },
    { "option_code": "…", "option_title": "Trekhaak, wegklapbaar", "msrp": 690, ... }
  ],
  "standard_equipment": [
    { "schema_id": "401",
      "description": "Style trim level - JATO classification: …",
      "local_description": "Finition: STYLE, …" }  // only when language was sent
  ]
}

Reading the response

• msrp is the option's list price in EUR at build; 0 with match_category: "Matched" means no-cost, otherwise treat it as included.

• match_score is 0–1. A sensible presentation: ≥ 0.9 high, ≥ 0.7 medium, below that low. Options can also be inferred from sheet-matched options that require them; match_category says so.

• option_title is already in the market's language. option_details is English; option_local_details is the localised equivalent when language was requested. Same pattern for description / local_description on standard equipment.

Language tags. en en-GB en-AU es de it fr nl fr-BE nl-BE. Use nl for the Netherlands. For Belgium and Luxembourg use fr-BE / nl-BE: JATO ships Luxembourg the Belgian pair, so region alone cannot pick one. The API resolves the vehicle's actual local language itself, so asking for fr-BE on a French car still returns French. Omit language and the response is byte-for-byte the English default.

Part B · Valuation

Valuations need an AutoGrab catalogue id, not the JATO id from step 1, and they run on the valuation key. In most regions the plain VIN lookup's id values directly.

3. Bridge: find the AutoGrab id by searching the catalogue

Free-text search over the catalogue. Build the query from the whole step 3 attribute set, not just the title: year, make, model, badge, body, transmission, fuel, drive, power, doors, seats. Fall back to a shorter query (year make model badge) if the long one returns nothing.

curl -sS --http1.1 --max-time 300 -G \
  -H "ApiKey: <NL_MARKET_KEY>" \
  --data-urlencode "region=nl" \
  --data-urlencode "search=2021 Skoda Scala Style Hatchback Manual Petrol Front Wheel Drive 81 kW 5 doors 5 seats" \
  "https://api-v2.eu.autograb.com/v2/vehicles"

// 200 — three candidates; note the first is the automatic
{ "success": true, "total": 3, "confidence": "reduced",
  "vehicles": [
    { "id": "3487199763117519", "title": "2021 Škoda Scala Style Petrol Auto",
      "transmission_type": "Automatic", "num_seats": 4, "power_kw": 81, ... },
    { "id": "4141773826623455", "title": "2021 Škoda Scala Style Petrol Auto",
      "transmission_type": "Automatic", "num_seats": 5, "power_kw": 81, ... },
    { "id": "4871984789026058", "title": "2021 Škoda Scala Style Petrol Manual",
      "transmission_type": "Manual",    "num_seats": 5, "power_kw": 81, ... }
  ] }

Pick the candidate that agrees with the step 3 vehicle field by field, not the first result. Compare each attribute the VIN car has (year, make, model, badge, body_type, transmission_type, fuel, drive_type, power_kw within ±3 kW, num_doors, num_seats); +1 for a match, −1 for a contradiction. Where a candidate omits a field (the NL catalogue leaves fuel null) but its title carries the value, count a partial match. Normalise diacritics and case first: Skoda must equal Škoda.

Candidate	Variant	Score
3487199763117519	Auto, 4 seats	6.75
4141773826623455	Auto, 5 seats	8.75
4871984789026058	Manual, 5 seats	10.75 ✓

Record the chosen title as well as the id. It is the variant you are about to value, and it can differ from the step 3 title, so show it to the user (Valued as: 2021 Škoda Scala Style Petrol Manual).

4. Value the matched id

curl -sS --http1.1 --max-time 300 -X POST \
  -H "ApiKey: <NL_MARKET_KEY>" -H "Content-Type: application/json" \
  --data '{"region": "nl", "vehicle_id": "4871984789026058", "features": ["bounds"]}' \
  "https://api-v2.eu.autograb.com/v2/valuations/predict"

// 200
{
  "success": true,
  "prediction": {
    "id": "…", "vehicle_id": "4871984789026058",
    "kms": 92500,                // market-average odometer, because none was sent
    "price": 15344,
    "retail_price": 15344,
    "trade_price": 11844,
    "score": 0.38,               // model confidence, 0–1
    "adjustment": null
  },
  "bounds": {
    "retail": { "lower": 14344, "upper": 16594 },
    "trade":  { "lower": …,     "upper": … }
  }
}

Odometer. To value at a known reading, add "kms": 30000 to the body; prediction.kms then echoes your figure. With no kms, treat prediction.kms as the market-average reading the price assumes and say so in the UI. Re-valuing after an odometer edit only needs this call again with the same id; there is no reason to repeat steps 3–5.

Bounds not licensed. If the key is not entitled to the bounds feature the whole call fails with Invalid or disallowed overlay feature: 'apis.valuation.features.bounds'. Retry without features; you get the prediction with no bounds object. Ask for bounds first and fall back, rather than never asking.

Part C · Market Insights

Insights need an AutoGrab catalogue id, not the JATO id from step 1.

5. Generate Market Insights

To understand the insights send the AutoGrab ID you found in the earlier step to the market_overlay endpoint

curl --location 'https://api-v2.eu.autograb.com/v2/sourcing/market_overlay/statistics/7554365546684842?region=nl&features=avg_price%2Cdays_supply%2Cavg_kms' \
--header 'ApiKey: KEY'

You will recieve back summary statistics on the market setting for that partticular vehicle ID.

{"success":true,"sample_size":6,"days_checked":360,"outlier_count":0,
 "avg_days_to_sell":9.07,"days_supply":720,"avg_price":46669,
 "avg_odometer":141080,"avg_kms":141080}