GET /v1/vin/{vin}
Decode a VIN and list known lots/listings
Decode a VIN and list known lots/listings
Decodes the VIN (NHTSA vPIC + WMI country/US-origin) and returns lots and listings with this VIN that the platform has seen (active and removed). If the decoder is down, specs is null with a warning and cached listings are still returned. Requires scope read:listings.
- Authentication: header
Authorization: Bearer rv_live_...(API keys and scopes) - Required scope:
read:listings
openapi.json).Parameters
| Field | In | Type | Required | Description |
|---|---|---|---|---|
vin | path | string | yes | 17-character VIN (letters I, O, Q are not allowed). Spaces and dashes are ignored. |
Responses
200
Decoded VIN and known listings.
application/json · Schema: VinResponse
| Field | Type | Required | Description |
|---|---|---|---|
vin | string | yes | |
validation | object | yes | |
validation.valid | boolean | yes | |
validation.warnings | string[] | yes | |
validation.check_digit | object | yes | |
specs | object | yes | Decoded specs (NHTSA vPIC + WMI). null if the decoder is unavailable. |
specs.vin | string | yes | |
specs.make | string | null | yes | |
specs.model | string | null | yes | |
specs.year | integer | null | yes | |
specs.trim | string | null | yes | |
specs.body | "sedan" | "hatchback" | "wagon" | "suv" | "crossover" | "coupe" | "convertible" | "minivan" | "van" | "pickup" | "truck" | "motorcycle" | "other" | null | yes | |
specs.fuel | "petrol" | "diesel" | "hybrid" | "phev" | "ev" | "lpg" | "cng" | "hydrogen" | "other" | null | yes | |
specs.engineCc | number | null | yes | |
specs.cylinders | number | null | yes | |
specs.powerKw | number | null | yes | |
specs.drive | "fwd" | "rwd" | "awd" | "4wd" | null | yes | |
specs.gearbox | "manual" | "automatic" | "cvt" | "robot" | "other" | null | yes | |
specs.plantCountry | string | null | yes | |
specs.wmiCountry | string | null | yes | |
specs.isUsOrigin | boolean | null | yes | |
decoder | object | yes | |
decoder.mode | "live" | "test" | "mock" | yes | |
decoder.error | string | null | yes | |
listings | object[] | yes | Lots/listings with this VIN known to the platform cache, newest first. |
listings[].source_key | string | no | |
listings[].external_id | string | no | |
listings[].url | string | no | |
listings[].title | string | no | |
listings[].status | "active" | "removed" | no | removed: the listing disappeared from the source (usually sold or taken down). |
listings[].price | object | no | |
listings[].price_eur | number | null | no | |
listings[].price_type | "fixed" | "current_bid" | "buy_now" | "estimate" | "unknown" | no | |
listings[].mileage_km | number | null | no | |
listings[].market | "us" | "eu" | "cn" | "kr" | "ua" | "ge" | no | |
listings[].auction | object | no | |
listings[].location_country | string | null | no | |
listings[].first_seen_at | string (date-time) | no | |
listings[].last_seen_at | string (date-time) | no | |
listings[].removed_at | string | null (date-time) | no | |
listings[].fetched_at | string (date-time) | no | |
warnings | object[] | yes | |
warnings[].code | string | no | |
warnings[].message | string | no |
400
Invalid request parameters or body (code validation_error).
application/problem+json · Schema: Problem
401
Missing, malformed, unknown, revoked or expired API key (code unauthorized).
application/problem+json · Schema: Problem
403
The API key lacks the scope required by this endpoint (code insufficient_scope).
application/problem+json · Schema: Problem
429
Rate limit exceeded for the tenant plan (code rate_limited). Wait Retry-After seconds.
application/problem+json · Schema: Problem
Example
curl -s "https://api.importos.app/v1/vin/1HGCM82633A004352" \
-H "Authorization: Bearer $IMPORTOS_API_KEY"