Decode Vehicle by VIN

Resolve a 17-character VIN to a normalized vehicle record with electrification fields and technical details.

GET /api/v1/vin/decode

Use this endpoint when you have a VIN and need the core ARC vehicle payload for downstream analytics, validation, or enrichment.

Authentication

Include X-API-Key on every request. Public API access is server-to-server only.

Idempotency

Include an Idempotency-Key with every request. Use a unique value for each logical request, and reuse the same value only when retrying that exact request. Use a new key when any input changes.

What to expect for response time

Most single VIN lookups return in under a second. The first request after a quiet period may take up to about 10 seconds while ARC warms up its decode pipeline—subsequent requests are typically much faster.

Caching

Successful VIN decode responses are returned with Cache-Control: private, no-store.

Decode warnings

A response with decode_status set to decoded_with_warnings is still a successful decode. Inspect decode_warnings before relying on fields affected by VIN quality or record coverage. feedback_unavailable means diagnostic feedback could not be established.

Query Parameters

Field	Type	Description
vin	string	Required. The 17-character Vehicle Identification Number to decode.

Example Request

cURL

curl "https://api.autoresourceco.com/api/v1/vin/decode?vin=5YJ3E1EA8KF000001" \
  -H "X-API-Key: your_api_key_here" \
  -H "Idempotency-Key: vin-decode-example-001"

Response Example

JSON

{
  "VIN": "1n4az1bv5nc000001",
  "Year": 2022,
  "Make": "NISSAN",
  "Model": "Leaf",
  "Trim": "S",
  "ElectrificationLevel": "BEV",
  "decode_status": "decoded",
  "decode_warnings": [],
  "suggested_vin": null,
  "possible_values": null,
  "technical_details": {
    "body_class": "Hatchback/Liftback/Notchback",
    "vehicle_type": "PASSENGER CAR",
    "drive_type": "4x2",
    "fuel_type_primary": "Electric",
    "fuel_type_secondary": null,
    "series": null,
    "ev_drive_unit": null,
    "battery_type": null,
    "battery_energy_kwh_from": null,
    "battery_energy_kwh_to": null,
    "battery_voltage_from": null,
    "battery_voltage_to": null,
    "battery_modules_per_pack": null,
    "battery_cells_per_module": null,
    "charger_level": null,
    "charger_power_kw": "40",
    "wheel_base_inches": null,
    "curb_weight_lbs": null,
    "gvwr": "Class 1: 6,000 lb or less (2,722 kg or less)",
    "track_width_inches": null,
    "engine_configuration": null,
    "engine_cylinders": null,
    "displacement_l": null,
    "transmission_style": "Continuously Variable Transmission (CVT)",
    "air_bag_locations": null,
    "plant_city": "SMYRNA",
    "plant_country": "UNITED STATES (USA)",
    "plant_company_name": "Nissan North America Inc."
  }
}

Response Fields

Field	Type	Description
VIN	string	Normalized VIN returned after validation and decode.
Year	integer	Resolved model year for the decoded vehicle.
Make / Model / Trim	string	Human-readable vehicle identity fields returned by ARC.
ElectrificationLevel	string \| null	ARC classification for electrification such as BEV, PHEV, HEV, or FCEV.
decode_status	"decoded" \| "decoded_with_warnings" \| "feedback_unavailable"	Indicates whether the decoder reported no warnings, reported warnings, or did not supply a valid feedback envelope. Blank vehicle fields do not establish that a feature is absent.
suggested_vin / possible_values	string \| null / object[] \| null	Candidate corrections for codes 1005–1009, checked against the submitted VIN. suggested_vin may mark an unresolved character with !. possible_values lists the allowed characters for each corrected position, such as [{"position": 11, "allowed": "A"}], including single-character corrections. position is the 1-based VIN position; allowed is a string of candidate characters. Either field can be null when unavailable or invalid. Verify all candidates against the vehicle.
decode_warnings	object[]	Stable ARC diagnostic codes and explanations. These warnings provide review guidance without turning a successful decode into an error.
technical_details	object	Expanded vehicle specifications including body, drivetrain, and plant metadata.

VIN Diagnostic Codes

Codes are returned as strings. Code 1000 is the clean marker and is omitted from decode_warnings. Every other listed code may appear in decode_warnings without turning the result into a failed request.

Code	Condition	Public Message	Response Behavior
1000	Checks completed without a reported issue	VIN checks completed without a reported issue.	Clean marker. It is not included in decode_warnings.
1001	Incomplete VIN	Only part of the VIN was supplied. Provide the complete VIN for a more complete result.	Successful decode warning when partial input reaches the decoder.
1002	Unsupported model-year character	Position 10 is not a supported model year character. Verify the VIN before relying on the decoded details.	Successful decode warning; request validation may reject the VIN first.
1003	Supplied and encoded model years conflict	The supplied model year conflicts with the year encoded in the VIN. Verify both inputs and submit them again.	Successful decode warning, most relevant to batch requests that supply years.
1004	VIN checksum mismatch	The VIN checksum does not match. Verify the character in position 9 and the rest of the VIN.	Successful decode warning; public request validation may reject the VIN first.
1005	Several VIN positions need verification	Several VIN positions need verification. Compare the submitted VIN with the vehicle identification plate.	Successful decode warning.
1006	Unsupported VIN characters	The VIN contains unsupported characters. Check the submitted letters and numbers.	Successful decode warning; public request validation may reject the VIN first.
1007	One VIN-character correction identified	A correction was identified for one VIN character. Confirm the suggested VIN against the vehicle.	Successful decode warning; suggested_vin may contain the candidate correction.
1008	One correction identified using the checksum	A correction was identified for one VIN character using the supplied checksum. Confirm both against the vehicle.	Successful decode warning; suggested_vin may contain the candidate correction.
1009	Multiple VIN-character corrections are possible	More than one correction fits a VIN character. Review the position marked ! in the suggested VIN and the available alternatives.	Successful decode warning; suggested_vin and possible_values may contain candidates.
1010	Manufacturer registration not found	No manufacturer registration for U.S. road use was found in the available records. Confirm the vehicle details with its manufacturer.	Successful decode warning.
1011	Detailed specifications unavailable	The available records do not contain detailed specifications for this VIN.	Successful decode warning; decoded fields may be blank.
1012	Manufacturer records explain only part of the VIN	The available manufacturer records explain only part of this VIN. Some vehicle details could not be determined.	Successful decode warning; decoded fields may be blank.
1013	Glider identifier	This identifier describes a glider rather than a complete motor vehicle. It does not qualify for a standard U.S. motor vehicle VIN.	Successful decode warning.
1014	Equipment intended for off-road use	This identifier describes equipment for use off public roads. It does not establish certification to U.S. motor vehicle safety standards.	Successful decode warning.
1015	Model year could not be established reliably	The model year could not be established reliably. If known, supply the model year and decode the VIN again.	Successful supplemental decode warning.
1090	Unclassified or legacy validation condition	A VIN validation condition needs review. Verify the VIN and the decoded details before using this result.	Safe fallback for an unknown, malformed, or legacy diagnostic code.
1091	Unclassified supplemental decode information	Additional decode information requires review. Verify the VIN, model year, and any suggested corrections.	Safe fallback for supplemental information that has no specific public code.

VIN Error Codes

Failed VINs use the same required four-digit codes in single-response detail.code and batch errors[].code. Use the code for program logic and the message for people.

Code	Condition	Public Message	Response Behavior
1001	VIN is shorter than 17 characters	VIN must be exactly 17 characters (received {length})	Rejected before decode; returned in detail.code or errors[].code.
1004	VIN checksum mismatch	VIN check digit (position 9) is invalid	Rejected before decode; returned in detail.code or errors[].code.
1006	VIN contains unsupported characters	VIN contains invalid characters (must be A-H, J-N, P, R-Z, 0-9; excludes I, O, Q)	Rejected before decode; returned in detail.code or errors[].code.
1020	VIN is missing or blank	VIN is required	Rejected before decode.
1021	VIN is longer than 17 characters	VIN must be exactly 17 characters (received {length})	Rejected before decode.
1022	VIN contains whitespace	VIN cannot contain whitespace	Rejected before decode.
1023	VIN contains a URL	VIN cannot contain URLs	Rejected before decode.
1024	VIN contains a percent character	VIN cannot contain "%" characters	Rejected before decode.
1092	VIN decode failed	The VIN could not be decoded.	No successful vehicle result was produced.
1093	Vehicle data unavailable for the VIN	No vehicle data was returned for this VIN.	No successful vehicle result was produced.
1094	Vehicle decoding service could not complete the VIN	The vehicle decoding service could not complete this VIN.	No successful vehicle result was produced.
1095	Vehicle data response could not be processed	The vehicle data response could not be processed.	No successful vehicle result was produced.
1096	Decoded vehicle is missing model year, make, or model	Decoded vehicle is missing a valid model year	Explorer by-VIN only: the VIN decoded, but battery fitment could not be resolved. Returned with HTTP 422. The message names the missing field (model year, or make or model), and decode_warnings and suggested_vin carry any VIN checks that explain the gap.

Related Docs

Authentication Errors and Limits