Lookup

Look up a real vehicle by VIN (Beta)

GET/vin/{vin}

> Beta. This endpoint is live and usable, but still evolving: response fields may change, and decoding coverage and catalogue matching are being improved. Feedback is welcome. Please do not build anything mission-critical on the exact response shape yet.

Decode a 17-character VIN into vehicle data and get studio images of the matching car in one call.

Add-on: must be enabled for your key. Check features.vin in /api/me; without it the endpoint returns 403.

What you get back

The decoded vehicle, make, model, year, trim, body, engine, transmission, drivetrain.
A vehicle block with the closest car from our catalogue and one signed image URL per view your plan allows.

Matching is automatic: the decoded make/model/year/body is mapped onto our catalogue, picking the generation that covers the vehicle's year. Read vehicle.confidence to see how close the match is, and vehicle.matched: false when nothing suitable exists. The decoded data is still returned in that case.

Invalid VINs are rejected with 400 before anything is charged. A VIN that cannot be decoded returns 404.

Path parameters

Name	Type	Description
`vin` required	string	17-character Vehicle Identification Number (letters I, O and Q are never used).

Request

curl "https://api.vehicleimagery.com/vin/vin" \
  -H "x-api-key: YOUR_API_KEY"

200 · Decoded vehicle plus the matched catalogue car and its images.

{
  "vin": "WBA8E9G50GNT47251",
  "make": "BMW",
  "model": "3 Series",
  "year": 2016,
  "trim": "328i",
  "body": "Sedan",
  "engine": {
    "name": "328i",
    "cylinders": 4,
    "displacement_ccm": 1997,
    "horsepower": 240,
    "fuel": "premium unleaded",
    "configuration": "inline"
  },
  "transmission": "AUTOMATIC",
  "drivetrain": "rear wheel drive",
  "doors": "4",
  "vehicle": {
    "matched": true,
    "confidence": "high",
    "id": 993477403,
    "brand": "BMW",
    "model": "3",
    "year": 2012,
    "variant": "Basis",
    "trim": "base",
    "color": "default",
    "images": {
      "front": "https://cdn.vehicleimagery.com/…",
      "front_left": "https://cdn.vehicleimagery.com/…"
    }
  }
}

400 · The VIN is not a valid 17-character VIN. Nothing is charged.

{
  "error": "Invalid VIN: expected 17 characters (letters I, O, Q are not used)."
}

403 · The VIN add-on is not enabled for your key.

{
  "error": "The vin add-on is not enabled for your API key."
}

404 · No data could be found for this VIN.

{
  "error": "No data found for this VIN.",
  "vin": "WBA8E9G50GNT47251"
}

502 · Lookup temporarily unavailable, retry shortly. Nothing is charged.

{
  "error": "VIN lookup temporarily unavailable."
}