OEM Build Data API

Retrieve complete vehicle build information including trim, colors, options, and MSRP data, or browse the year/make/model catalog

Retrieve complete vehicle build information based on the VIN, including exact trim details, drivetrain, engine specifications, interior/exterior colors, factory options, and MSRP data. This comprehensive API provides the most detailed vehicle information available from OEM build records.

If you do not have a VIN, the vehicle catalog lists makes and models with the model years recorded for each, in a single request.

A VIN that decodes to a car but has no build record answers 207 Multi-Status with the vehicle and what its style ships with, never a fabricated build. See partial answers. A build that lacks a color or its options says so in missing.

Endpoint

GET https://api.auto.dev/build/{vin}

To browse the catalog without a VIN, see the vehicle catalog below.

GET https://api.auto.dev/build/ymm

View in Browser

https://api.auto.dev/build/1FTFW3LDXRFB40317

Parameters

Prop	Type	Default
`vin`	`string`	-

Example Request

curl -X GET "https://api.auto.dev/build/1FTFW3LDXRFB40317" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Structure

Example Response

{
  "build": {
    "vin": "1FTFW3LDXRFB40317",
    "year": 2024,
    "make": "Ford",
    "model": "F-150",
    "trim": "XLT",
    "series": "XLT",
    "style": "4D SuperCrew",
    "drivetrain": "4WD",
    "engine": "3.5L V-6 gasoline direct injection, DOHC, twin turbocharged, regular unleaded, engine with 400HP",
    "transmission": "10-speed automatic",
    "confidence": 0.99,
    "interiorColor": {
      "Black Onyx": "#1C1C1C"
    },
    "exteriorColor": {
      "Iconic Silver Metallic": "#C0C0C0"
    },
    "options": {
      "53A": "XLT Mid Equipment Group",
      "99N": "Iconic Silver Metallic",
      "FX4": "FX4 Off-Road Package",
      "86M": "Trailer Tow Package"
    },
    "optionsMsrp": 4295,
    "headUpDisplay": false,
    "rainSensingWipers": false
  }
}

Missing Fields

A 200 is what the record for this VIN says. When no record held one of interiorColor, exteriorColor or options, the response lists it in a top-level missing array. The key is absent when nothing is missing, and build is the same either way.

{
  "build": {
    "vin": "19XFL2H80TE045314",
    "year": 2026,
    "make": "Honda",
    "model": "Civic Hatchback",
    "trim": "Sport",
    "style": "Hatchback 4D",
    "drivetrain": "FWD",
    "engine": "2.0L I4",
    "transmission": "CVT",
    "confidence": 0.85,
    "options": {},
    "headUpDisplay": false,
    "rainSensingWipers": false
  },
  "missing": [
    { "field": "interiorColor", "reason": "no_vin_record" },
    { "field": "exteriorColor", "reason": "no_vin_record" }
  ]
}

Prop	Type	Default
`missing[].field?`	`string`	-
`missing[].reason?`	`string`	-

An empty options object is not always a gap. The example above is a base vehicle: the record names the trim and lists nothing optional, so options: {} is the answer and only the colors are missing. options appears in missing only when a record exists for the VIN but holds no option list.

A build with missing fields bills as a full build.

Partial Answers (207)

When a VIN decodes to a car but no record builds it, /build answers 207 Multi-Status instead of a 404: the vehicle the decoder named, build: null, what the matched style ships with, and why. A catalog option carries the manufacturer's code when it is known, and code: null otherwise; a catalog code says the style offers the option, not that this VIN has it.

{
  "vehicle": {
    "vin": "1C4RJHBR3V8175351",
    "year": 2027,
    "make": "Jeep",
    "model": "Grand Cherokee",
    "body": "Suv 4D"
  },
  "build": null,
  "catalog": {
    "vinSpecific": false,
    "styles": [
      {
        "name": "Limited Reserve 4dr SUV 4WD (2.0L 4cyl Turbo 8A)",
        "trim": "Limited Reserve",
        "confidence": 0.85,
        "msrp": 52555
      },
      {
        "name": "Limited 4dr SUV 4WD (2.0L 4cyl Turbo 8A)",
        "trim": "Limited",
        "confidence": 0.15,
        "msrp": 46960
      }
    ],
    "standardEquipment": ["Dual fuel injection", "Full time 4WD", "Electronic single speed"],
    "availableOptions": [
      { "code": null, "name": "Mopar finishing package" },
      { "code": null, "name": "Trailer tow package" }
    ],
    "exteriorColors": [
      { "name": "Sting-Gray Clear Coat", "colorCode": "#5E5E5E" },
      { "name": "High Gloss Black", "colorCode": "#000000" }
    ],
    "interiorColors": [{ "name": "Global Black, leatherette", "colorCode": "#000000" }]
  },
  "reason": "not_yet_available",
  "retryable": true
}

A 207 passes the ok check of most HTTP clients, and build is null. Branch on the status, or on build === null, before reading build:

const res = await fetch(`https://api.auto.dev/build/${vin}`, {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
})
const data = await res.json()

if (res.status === 207) {
  // data.vehicle names the car; data.build is null; data.catalog is what the style ships with, or null.
  // data.reason says why; ask again later when data.retryable is true.
} else if (res.ok) {
  console.log(data.build)
}

Response Structure (207)

Reason Codes

Every miss, 207 or 404, carries reason and retryable. "If decoded" means a decoder named the year, make and model; otherwise the same reason rides a 404.

`reason`	status	means	retry
`not_yet_available`	207 if decoded, else 404	model year ahead of the catalogs	yes, the catalogs catch up within the year
`no_build_record`	207 if decoded, else 404	no record builds this VIN	no
`market_not_covered`	207 if decoded, else 404	non-North-American VIN; `catalog` is `null`	no
`class_not_covered`	207 if decoded, else 404	motorcycle, trailer or heavy truck; `catalog` is `null`	no
`invalid_vin`	404	the check digit does not compute, or the VIN is a test pattern	no

A vehicle-only 207, a motorcycle outside build coverage:

{
  "vehicle": {
    "vin": "1HD1BWV10GB016330",
    "year": 2016,
    "make": "Harley-davidson",
    "model": "Flstc103 / Heritage Softail Classic",
    "body": "Motorcycle - Custom"
  },
  "build": null,
  "catalog": null,
  "reason": "class_not_covered",
  "retryable": false
}

A 404 is reserved for a VIN no decoder can name. See error responses.

Billing

A 207 is not a billed call and counts toward no quota.

Vehicle Catalog

Lists the makes and models OEM Build Data reliably serves, with the range of model years for each. No VIN is required, and the catalog is returned in a single request.

The catalog is built from the build data we have returned. A model year of a make and model is listed when full build data (a 200) has been returned for at least two different VINs of it, and for at least half of its lookups: those of the last 180 days when it was looked up in them, otherwise all of them. The years are the range from the first to the last such year, so a year inside the range can still be missing, and a listed vehicle does not guarantee a build record for a particular VIN. Use the catalog to browse and to build pickers; use GET /build/{vin} to find out what exists for a specific vehicle.

GET https://api.auto.dev/build/ymm

https://api.auto.dev/build/ymm

This endpoint takes no parameters.

Example Request

curl -X GET "https://api.auto.dev/build/ymm" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Structure

Each top-level key is a make. Each value maps a model name to its range of model years, or to a single year.

{
  "Acura": {
    "ILX": "2013-2022",
    "MDX": "2009-2026"
  },
  "Toyota": {
    "4Runner": "1997-2026",
    "86": "2019-2020",
    "RAV4": "2007-2026"
  }
}

Billing

Catalog requests bill as OEM Build Data, at the same rate as a VIN lookup. Repeated catalog requests within the same day count once.

Use Cases

Appraisal Services: Factor in factory options and original colors for accurate vehicle valuations
Insurance Underwriting: Use confidence scores and build specifications for risk assessment
Parts & Service: Match exact factory option codes for correct parts ordering
Catalog & Search: Build make/model pickers and check coverage before looking up a VIN

Error Responses

Invalid VIN

The VIN is not 17 valid characters. A well-formed VIN that is not a vehicle is a 404 INVALID_VIN instead (below).

{
  "error": {
    "status": 400,
    "error": "VIN must be exactly 17 characters containing only letters and numbers (excluding I, O, Q)",
    "code": "INVALID_VIN_FORMAT",
    "path": "/build/1FTFW3LDXRFB4031",
    "requestId": "a4b064e6ab9ba558"
  }
}

VIN Not Found

A 404 means no decoder could name the car, or the VIN is not a vehicle. A car a decoder names, with no build record, is a 207, not a 404. Every miss carries reason and retryable, top-level and inside error.

{
  "build": {
    "error": "No build data available",
    "vin": "1FMDU32X6RUE08716"
  },
  "reason": "no_build_record",
  "retryable": false,
  "error": {
    "status": 404,
    "error": "No build data available for this vehicle.",
    "code": "VIN_NOT_FOUND",
    "path": "/build/1FMDU32X6RUE08716",
    "requestId": "nu9cn44nt2ek5rbk",
    "reason": "no_build_record",
    "retryable": false
  }
}

Not a Vehicle

The check digit does not compute, or the VIN is a test pattern.

{
  "build": {
    "error": "No build data available",
    "vin": "11111111111111111"
  },
  "reason": "invalid_vin",
  "retryable": false,
  "error": {
    "status": 404,
    "error": "This VIN is not a vehicle: its check digit does not compute, or it is a test pattern.",
    "code": "INVALID_VIN",
    "path": "/build/11111111111111111",
    "requestId": "wk2t89y2ujo35ojs",
    "reason": "invalid_vin",
    "retryable": false
  }
}

VIN Not in Coverage

A non-North-American VIN, or a motorcycle, trailer or heavy truck, that no decoder named. error.detectedMarket or error.detectedClass says which. When a decoder names the car, the same VIN answers a 207 with catalog: null.

{
  "build": {
    "error": "No build data available",
    "vin": "6FPFXXMX2FRD07902"
  },
  "reason": "market_not_covered",
  "retryable": false,
  "error": {
    "status": 404,
    "error": "This VIN appears to be a non-US vehicle. auto.dev currently has full coverage for US-market vehicles only.",
    "code": "VIN_NOT_IN_COVERAGE",
    "path": "/build/6FPFXXMX2FRD07902",
    "requestId": "4k12o1tsrzyb4rai",
    "detectedMarket": { "country": "AU", "region": "Oceania" },
    "reason": "market_not_covered",
    "retryable": false
  }
}

Free: ❌ Not available
Growth: ✅ Available
Scale: ✅ Available

See pricing for plan details and signup.

OEM Build Data API

Endpoint

View in Browser

Parameters

Example Request

Response Structure

Example Response

Missing Fields

Partial Answers (207)

Response Structure (207)

Reason Codes

Billing

Vehicle Catalog

Example Request

Response Structure

Billing

Use Cases

Error Responses

Invalid VIN

VIN Not Found

Not a Vehicle

VIN Not in Coverage

Interactive API Reference

Try OEM Build Data API

Plan Availability

On this page

OEM Build Data API

Basic Vehicle Information

Mechanical Specifications

Color Information

Factory Options & Pricing

Equipment Detection

Vehicle

Catalog

Reason

Try OEM Build Data API

On this page