VIN

live

Identity: VIN → refs, grains, links

GET/v2/vin/{vin}

Decode a VIN to its graph identity

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

Path parameters

ParameterType
curl "https://api.cardog.app/v2/vin/1HGCM82633A123456" \
  -H "x-api-key: $CARDOG_API_KEY"

Response 200 — VinIdentity

FieldType

Example response

12 keys
"response": {
"vin": "1FTFW1E84PKE12345",
"valid": true,
"year": 2023,
"make": "Ford",
"model": "F-150",
"trim": "SuperCrew",
"trimAuthorityTier": "derived",
"observedTrim": null,
"refs": {
"make": "make:ford",
"model": "model:ford/f-150",
"modelYear": "model-year:ford/f-150/2023",
"bodyStyle": "body-style:pickup",
"fuelType": "fuel-type:gasoline",
"driveType": null,
"transmission": null,
"electrificationLevel": null,
"vehicleType": null,
"country": null
},
"nano": "nano:1FTFW1E8PK",
"squish": "squish:1FTFW1E8P",
"links": {
"instrument": "/v2/vin/1FTFW1E84PKE12345/instrument",
"recalls": "/v2/vin/1FTFW1E84PKE12345/recalls",
"listings": "/v2/vin/1FTFW1E84PKE12345/listings",
"makeEntity": "/v2/entities/make%3Aford",
"modelEntity": "/v2/entities/model%3Aford%2Ff-150",
"specs": "/v2/specs/model-year%3Aford%2Ff-150%2F2023",
"quote": "/v2/quotes/model-year%3Aford%2Ff-150%2F2023",
"safety": "/v2/safety/model-year%3Aford%2Ff-150%2F2023"
}
}

Errors — every non-2xx body is the error envelope: 400, 401, 402, 429, 500

POST/v2/vin/batch

Batch decode (metered per VIN)

N VINs = N metered units. Per-item outcomes: one bad VIN fails its own row, never the batch.

Request body — VinBatchRequest

FieldType
curl -X POST "https://api.cardog.app/v2/vin/batch" \
  -H "x-api-key: $CARDOG_API_KEY" \
  -H "content-type: application/json" \
  -d '{"vins":["1HGCM82633A123456"]}'

Response 200 — VinBatchResponse

FieldType

Example response

2 keys
"response": {
"results": [
0: {3 items},
1: {3 items}
],
"meta": {
"requested": 2,
"decoded": 2,
"failed": 0
}
}

Errors — every non-2xx body is the error envelope: 400, 401, 402, 429, 500

GET/v2/vin/{vin}/instrument

VIN → market instrument bridge

Path parameters

ParameterType
curl "https://api.cardog.app/v2/vin/1HGCM82633A123456/instrument" \
  -H "x-api-key: $CARDOG_API_KEY"

Response 200 — VinInstrument

FieldType

Example response

4 keys
"response": {
"vin": "1FTFW1E84PKE12345",
"squishRef": "squish:1FTFW1E8P",
"mmy": null,
"links": {
"identity": "/v2/vin/1FTFW1E84PKE12345",
"instrument": "/v2/instruments/squish%3A1FTFW1E8P"
}
}

Errors — every non-2xx body is the error envelope: 400, 401, 402, 429, 500

GET/v2/vin/{vin}/recalls

Recalls affecting a VIN (the authoritative recall check)

Path parameters

ParameterType
curl "https://api.cardog.app/v2/vin/1HGCM82633A123456/recalls" \
  -H "x-api-key: $CARDOG_API_KEY"

Response 200 — RecallsVin

FieldType

Example response

8 keys
"response": {
"vin": "1FTFW1E84PKE12345",
"modelYearRef": "model-year:ford/f-150/2023",
"resolved": true,
"source": "decoded",
"total": 30,
"recalls": [
0: {13 items},
1: {13 items},
2: {13 items},
3: {13 items},
4: {13 items},
5: {13 items},
6: {13 items},
7: {13 items},
8: {13 items},
9: {13 items},
10: {13 items},
11: {13 items},
12: {13 items},
13: {13 items},
14: {13 items},
15: {13 items},
16: {13 items},
17: {13 items},
18: {13 items},
19: {13 items},
20: {13 items},
21: {13 items},
22: {13 items},
23: {13 items},
24: {13 items},
25: {13 items},
26: {13 items},
27: {13 items},
28: {13 items},
29: {13 items}
],
"asOf": "2026-07-31T06:03:14.613Z",
"links": {
"identity": "/v2/vin/1FTFW1E84PKE12345",
"entity": "/v2/recalls/entity/model-year%3Aford%2Ff-150%2F2023"
}
}

Errors — every non-2xx body is the error envelope: 400, 401, 402, 429, 500

GET/v2/vin/{vin}/listings

Listing detail for a VIN (listing + vehicle + canonical spec)

Path parameters

ParameterType
curl "https://api.cardog.app/v2/vin/1HGCM82633A123456/listings" \
  -H "x-api-key: $CARDOG_API_KEY"

Response 200 — ListingDetail

FieldType

Example response

63 keys
"response": {
"id": "87dc1b59-771d-475b-a6b7-37dd96df2516",
"vin": "5NPE34AFXHH588415",
"price": 14888,
"currency": "CAD",
"odometer": 94743,
"year": 2017,
"make": "Hyundai",
"model": "Sonata",
"trim": "Sport Tech",
"makeRef": "make:hyundai",
"modelRef": "model:hyundai/sonata",
"nano": null,
"media": [
0: {3 items},
1: {3 items},
2: {3 items},
3: {3 items},
4: {3 items},
5: {3 items},
6: {3 items},
7: {3 items},
8: {3 items},
9: {3 items},
10: {3 items},
11: {3 items},
12: {3 items},
13: {3 items},
14: {3 items},
15: {3 items},
16: {3 items},
17: {3 items},
18: {3 items},
19: {3 items}
],
"variant": null,
"spec": null,
"sellerId": "d98113ad-d5a7-4256-86ac-197c2842560c",
"websiteDomain": "motoauto.ca",
"sourceUri": "https://www.motoauto.ca/inventory/2017-hyundai-sonata-sport-tech/272/",
"stockNumber": "588415",
"score": 76,
"status": "active",
"mediaCount": 22,
"latitude": "53.57040000",
"longitude": "-113.47100000",
"location": {
"id": 35053,
"street": "8419 118 Ave NW",
"city": "Edmonton",
"state": "AB",
"postalCode": "T5B 0S6",
"country": "CA",
"latitude": "53.5704",
"longitude": "-113.471",
"location": {2 items},
"createdAt": "2025-02-09T07:43:40.075Z",
"updatedAt": "2025-02-09T07:43:40.075Z"
},
"createdAt": "2026-07-31T04:05:47.869Z",
"updatedAt": "2026-07-31T08:08:35.925Z",
"removedAt": null,
"previousPrice": null,
"priceChangedAt": null,
"verificationStatus": "verified",
"verificationReasons": [
],
"verifiedAt": "2026-07-31T08:08:35.925Z",
"lastSeenAt": "2026-07-31T08:08:35.925Z",
"bodyStyle": "sedan",
"fuelType": "gasoline",
"driveTrain": null,
"transmission": null,
"engineSize": null,
"horsepower": null,
"torque": null,
"exteriorColor": "Black",
"interiorColor": "Black",
"condition": "used",
"makeRaw": null,
"bodyStyleRef": "body-style:sedan-saloon",
"fuelTypeRef": "fuel-type:gasoline",
"driveTypeRef": null,
"transmissionRef": null,
"vehicleTypeRef": null,
"electrificationLevelRef": null,
"gvwrRef": null,
"cylinders": 4,
"displacement": "2.4",
"numberOfDoors": 4,
"shippingWeight": 3311,
"grossWeight": null,
"electrificationLevel": null,
"gvwr": null,
"vehicleType": "Passenger Car",
"seller": {
"id": "d98113ad-d5a7-4256-86ac-197c2842560c",
"type": "dealership",
"name": "Moto Auto",
"slug": "moto_auto",
"email": null,
"phone": null,
"addressId": 35053,
"dealershipId": "7efa15de-853a-41e3-a423-44529dc7c568",
"gmbPhone": "+17802442222",
"gmbRating": "4.7",
"gmbReviewCount": 286,
"createdAt": "2025-02-09T07:43:40.075Z",
"updatedAt": "2026-01-28T20:53:42.879Z",
"deactivatedAt": null
},
"dealership": {
"id": "7efa15de-853a-41e3-a423-44529dc7c568",
"name": "Moto Auto",
"primaryDomain": "motoauto.ca",
"metadata": {3 items},
"isVerified": true,
"createdAt": "2025-02-09T07:43:40.075Z",
"updatedAt": "2025-02-09T07:43:40.075Z"
},
"vehicle": {
"vin": "5NPE34AFXHH588415",
"make": "Hyundai",
"model": "Sonata",
"year": 2017,
"trim": "Sport Tech",
"bodyStyle": "sedan",
"fuelType": "gasoline",
"driveTrain": null,
"transmission": null,
"engineSize": null,
"horsepower": null,
"torque": null,
"exteriorColor": "Black",
"interiorColor": "Black",
"condition": "used",
"makeRef": "make:hyundai",
"modelRef": "model:hyundai/sonata",
"makeRaw": null,
"bodyStyleRef": "body-style:sedan-saloon",
"fuelTypeRef": "fuel-type:gasoline",
"driveTypeRef": null,
"transmissionRef": null,
"vehicleTypeRef": null,
"electrificationLevelRef": null,
"gvwrRef": null,
"nano": null,
"cylinders": 4,
"displacement": "2.4",
"numberOfDoors": 4,
"shippingWeight": 3311,
"grossWeight": null,
"electrificationLevel": null,
"gvwr": null,
"vehicleType": "Passenger Car",
"createdAt": "2026-07-31T04:05:47.160Z",
"updatedAt": "2026-07-31T04:05:47.160Z"
}
}

Errors — every non-2xx body is the error envelope: 400, 401, 402, 404, 429, 500

Generated from the contract. Machine-readable spec: GET https://api.cardog.app/v2/openapi.json · markdown twin: /docs/reference/vin.md