vin

Decode a VIN to its graph identity

Identity card: display names + entity refs + nano/squish grains + links to instrument, recalls, and listings.

get/v2/vin/{vin}

Request

  • Base URL: https://api.cardog.app
  • URL: https://api.cardog.app/v2/vin/{vin}
  • Auth: one of:
    • API key in header x-api-key
    • HTTP bearer

Path parameters

vinstring required

17-character VIN

Response

The identity card

vinstring required
validboolean required

Whether the VIN decodes to a vehicle. When false, every other field and every ref is null; the API does not fill in an unresolved VIN from similar vehicles.

yearinteger nullable required
doorsinteger nullable
trimstring nullable
numberOfWheelsinteger nullable
numberOfAxlesinteger nullable
shippingWeightinteger nullable
grossWeightinteger nullable
makestring nullable required

Display name. Use refs.make for joins.

modelstring nullable required

Display name. Use refs.model for joins.

nanostring nullable required

Build code ref (VIN positions 1–8 plus 10), e.g. "nano:5TDGSKFCRS". Vehicles sharing it are the same build, so use it as the deduplication and comparables key. Null when valid is false.

squishstring nullable required

Configuration key ref (WMI + VDS + model year, plant-agnostic), e.g. "squish:5TDGSKFCS". This is the level market prices are quoted at. Null when valid is false.

authorityTier'authoritative' | 'commercial' | 'derived' | 'observed'

Trust tier of the identity facts. Source documents are never identified.

reasonsstring[] nullable

Why the VIN yielded no identity, from a closed vocabulary of eleven in three classes. The engine's refusals, written beside a row: WMI_UNKNOWN, PATTERN_UNKNOWN, UNKNOWN_MODEL_YEAR, INVALID_LENGTH, INVALID_CHARACTERS, CHECK_DIGIT_MISMATCH, NON_STANDARD_CHECK_DIGIT. The fold's own, for a refusal the engine gives no code for: NO_PATTERN_MATCH, MAKE_REF_GRAMMAR. And two minted at the READ, which answer a different question — not 'why could we not name this build' but 'why is there no row to read': UNSEEN_BUILD (the build is well-formed and has never been decoded — distinct from decoded and refused, and the one the refresh top-up mints next) and UNKEYABLE_VIN (the VIN projects onto no build code, so there is no key). Non-empty whenever valid is false; null exactly when valid is true. Typed as strings on the wire on purpose: the row classes are closed by a CHECK on ocean.identity.status_reasons and the read class by the API, so a new code is a deliberate change and never breaks a client parsing this field.

corgiBuildstring nullable

Decoder build that minted this identity, e.g. "2026_08_3befa53".

attributesobject nullable

Non-entity decode output for this build. Not the spec sheet.

linksobject required

Server-relative paths to related resources. Always includes "instrument", "recalls", "listings", and one entity link per ref.

Changes

No recorded changes to this operation across all 1 revision of this API.