VIN Decoding

The VIN decoding endpoints provide comprehensive vehicle information by analyzing Vehicle Identification Numbers (VINs). These endpoints can decode VINs to extract detailed vehicle specifications, variants, and even process VIN images using AI.

GET/v1/vin/:vin

Decode VIN (Full)

This endpoint provides the most comprehensive VIN decoding, combining both VIN pattern matching and vehicle variant data. It first decodes the VIN using our Corgi decoder, then enriches the data with detailed variant information from our vehicle database.

Required parameters

Name
vin
Type
string
Description
A valid 17-character Vehicle Identification Number.

Request

GET

/v1/vin/1HGBH41JXMN109186

curl "https://api.cardog.io/v1/vin/1HGBH41JXMN109186" \
  -H "x-api-key: your-api-key"

Response

{
  "variants": [
    {
      "id": "honda-civic-2021-lx",
      "make": "Honda",
      "model": "Civic",
      "year": 2021,
      "trim": "LX",
      "msrp": 22350,
      "bodyStyle": "Sedan",
      "styleName": "Civic LX 4dr Sedan",
      "region": "US",
      "spec": {
        "engine": "1.5L 4-Cylinder",
        "transmission": "CVT",
        "drivetrain": "FWD"
      }
    }
  ],
  "pass": {
    "vin": "1HGBH41JXMN109186",
    "valid": true,
    "components": {
      "vehicle": {
        "make": "Honda",
        "model": "Civic",
        "year": 2021,
        "bodyStyle": "Sedan",
        "driveType": "FWD",
        "fuelType": "Gasoline"
      },
      "wmi": {
        "manufacturer": "Honda Motor Co., Ltd.",
        "make": "Honda",
        "country": "United States",
        "region": "North America"
      },
      "checkDigit": {
        "isValid": true,
        "expected": "X",
        "actual": "X"
      }
    }
  },
  "vin": "1HGBH41JXMN109186"
}

GET/v1/vin/nano/:vin

Decode VIN (Nano)

This endpoint provides a lightweight VIN lookup using our nano VIN database. It's optimized for speed and returns basic variant information without the full decoding process. Nano VINs are condensed 11-character identifiers that exclude the check digit.

Required parameters

Name
vin
Type
string
Description
A valid VIN (17, 11, or 10 characters). Will be automatically converted to nano format.

Request

GET

/v1/vin/nano/1HGBH41JXMN109186

curl "https://api.cardog.io/v1/vin/nano/1HGBH41JXMN109186" \
  -H "x-api-key: your-api-key"

Response

{
  "id": "honda-civic-2021-lx",
  "make": "Honda",
  "model": "Civic",
  "year": 2021,
  "trim": "LX",
  "msrp": 22350,
  "bodyStyle": "Sedan",
  "styleName": "Civic LX 4dr Sedan",
  "region": "US"
}

GET/v1/vin/corgi/:vin

Decode VIN (Corgi)

This endpoint provides raw VIN decoding using our Corgi decoder engine. It returns detailed pattern matching results, component analysis, and validation information without additional variant enrichment. Perfect for applications that need low-level VIN analysis.

Required parameters

Name
vin
Type
string
Description
A valid 17-character Vehicle Identification Number.

Request

GET

/v1/vin/corgi/1HGBH41JXMN109186

curl "https://api.cardog.io/v1/vin/corgi/1HGBH41JXMN109186" \
  -H "x-api-key: your-api-key"

Response

{
  "vin": "1HGBH41JXMN109186",
  "valid": true,
  "components": {
    "checkDigit": {
      "position": 8,
      "actual": "X",
      "expected": "X",
      "isValid": true
    },
    "modelYear": {
      "year": 2021,
      "source": "VIS_POSITION_10",
      "confidence": 1.0
    },
    "wmi": {
      "code": "1HG",
      "manufacturer": "Honda Motor Co., Ltd.",
      "make": "Honda",
      "country": "United States",
      "vehicleType": "Passenger Car",
      "region": "North America"
    },
    "vds": {
      "raw": "BH41JX",
      "patterns": [
        {
          "element": "Body Style",
          "code": "BH4",
          "attributeId": "body_style",
          "value": "Sedan",
          "confidence": 0.95,
          "positions": [3, 4, 5],
          "schema": "honda_passenger",
          "metadata": {
            "lookupTable": "honda_body_styles",
            "groupName": "Vehicle Description",
            "elementWeight": 0.8,
            "patternType": "direct_lookup",
            "rawPattern": "BH4"
          }
        }
      ]
    },
    "vis": {
      "raw": "MN109186",
      "patterns": [
        {
          "element": "Plant Code",
          "code": "M",
          "attributeId": "plant_code",
          "value": "Marysville, OH",
          "confidence": 1.0,
          "positions": [10],
          "schema": "honda_plant_codes",
          "metadata": {
            "lookupTable": "honda_plants",
            "groupName": "Manufacturing",
            "elementWeight": 1.0,
            "patternType": "plant_lookup",
            "rawPattern": "M"
          }
        }
      ]
    },
    "vehicle": {
      "make": "Honda",
      "model": "Civic",
      "year": 2021,
      "bodyStyle": "Sedan",
      "driveType": "FWD",
      "fuelType": "Gasoline",
      "doors": "4"
    }
  },
  "errors": [],
  "metadata": {
    "processingTime": 45.2,
    "confidence": 0.96,
    "schemaVersion": "1.0"
  }
}

POST/v1/vin/image

Extract VIN from Image

This endpoint uses AI to extract VIN numbers from images of vehicle dashboards or door jambs. It accepts base64-encoded images and returns the detected VIN using Google's Gemini vision model.

Required parameters

Name
image
Type
string
Description
Base64-encoded image data (without data URL prefix).

Request

POST

/v1/vin/image

curl "https://api.cardog.io/v1/vin/image" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg=="
  }'

Response

{
  "success": true,
  "result": "1HGBH41JXMN109186"
}

Error Responses

All VIN endpoints return structured error responses when validation fails or processing errors occur:

Invalid VIN Error

{
  "error": "Invalid VIN"
}

No Variant Found Error

{
  "error": "No variant found"
}

Image Processing Error

{
  "error": "Image data is required as base64 string"
}

VIN Format Support

Our VIN decoding endpoints support various VIN formats:

Name
17-character VIN
Type
string
Description
Full standard VIN format (e.g., "1HGBH41JXMN109186")
Name
11-character VIN
Type
string
Description
VIN with check digit included (e.g., "1HGBH41JXMN")
Name
10-character VIN
Type
string
Description
Nano VIN without check digit (e.g., "1HGBH41JMN")

Use Cases

Name
Full Decode
Type
endpoint
Description
Use /v1/vin/:vin when you need comprehensive vehicle information including variants, specifications, and detailed decoding results.
Name
Quick Lookup
Type
endpoint
Description
Use /v1/vin/nano/:vin for fast variant lookups when you only need basic vehicle information.
Name
Raw Analysis
Type
endpoint
Description
Use /v1/vin/corgi/:vin when you need detailed VIN pattern analysis and component breakdown.
Name
Image Processing
Type
endpoint
Description
Use /v1/vin/image to extract VINs from photos of vehicle dashboards or door jambs.