Batch Decode Vehicles by VIN

Decode multiple VINs in one request and receive successful results plus per-VIN validation or decode failures.

POST /api/v1/vin/decode-batch

Use batch decode for backfills, bulk imports, or queue workers that need to process multiple VINs while preserving partial success.

Authentication

Batch decode uses the same X-API-Key header contract as the single VIN endpoint.

Idempotency and batch replay

Include an Idempotency-Key with every request. Retrying the same batch with the same key returns its original response, including results and errors. Use a new key to submit changed inputs or intentionally run the VINs again.

What to expect for response time

Once warmed up, batch requests typically complete in under a second. The first batch after idle may take longer—often up to about 10 seconds—before throughput settles into the faster range.

Billing

Each successful VIN decode is billed individually. Invalid VINs and failed decodes are not billed.

Warnings versus errors

results[].decode_warnings describe a decode that completed and needs review. errors[] contains VINs that did not produce a successful result, and every entry includes a four-digit code. A warned result counts as successful in summary and billing; an errors[] entry counts as failed.

Request Body

Field	Type	Description
vins	string[]	Required. Array of VINs to decode. Maximum 50 VINs per request.
years	number[]	Optional. Optional model years aligned to the input VIN array. Extra values are ignored if a VIN is invalid.

Example Request

cURL

curl "https://api.autoresourceco.com/api/v1/vin/decode-batch" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -H "Idempotency-Key: vin-batch-example-001" \
  -d '{
    "vins": [
      "1N4AZ1BV5NC000001",
      "JTDKB20U48778057Z",
      "1HGCM82633A123456"
    ],
    "years": [2022, 2008, 2003]
  }'

Response Example

JSON

{
  "results": [
    {
      "VIN": "1n4az1bv5nc000001",
      "Year": 2022,
      "Make": "NISSAN",
      "Model": "Leaf",
      "Trim": "S",
      "ElectrificationLevel": "BEV",
      "decode_status": "decoded_with_warnings",
      "decode_warnings": [
        {
          "code": "1012",
          "message": "The available manufacturer records explain only part of this VIN. Some vehicle details could not be determined."
        }
      ],
      "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": "",
        "series": "",
        "ev_drive_unit": "",
        "battery_type": "",
        "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": "",
        "charger_power_kw": null,
        "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": "",
        "engine_cylinders": "",
        "displacement_l": "",
        "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."
      }
    }
  ],
  "errors": [
    {
      "vin": "JTDKB20U48778057Z",
      "code": "1004",
      "error": "VIN check digit (position 9) is invalid"
    },
    {
      "vin": "1HGCM82633A123456",
      "code": "1004",
      "error": "VIN check digit (position 9) is invalid"
    }
  ],
  "summary": {
    "total": 3,
    "successful": 1,
    "failed": 2
  }
}

Response Fields

Field	Type	Description
results	object[]	Successful vehicle decodes, returned in the same public payload shape as single VIN decode.
errors	object[]	Per-VIN validation or decode failures that did not prevent the overall batch response from completing.
errors[].code	string	Required four-digit ARC code identifying why this VIN did not produce a successful result.
errors[].error	string	ARC-owned explanation for the failed VIN. Use errors[].code for program logic.
results[].decode_status	"decoded" \| "decoded_with_warnings" \| "feedback_unavailable"	Per-result diagnostic state. feedback_unavailable means ARC could not establish a valid feedback envelope; it does not mean checks passed.
results[].decode_warnings	object[]	Successful-decode review guidance using the diagnostic codes below. These entries do not increase summary.failed.
results[].suggested_vin / results[].possible_values	string \| null / object[] \| null	Candidate corrections for codes 1005–1009, checked against each submitted VIN. possible_values lists {"position", "allowed"} entries and can accompany single or ambiguous corrections. Either field can be null when unavailable or invalid; verify candidates against the vehicle.
summary.total	integer	Total number of VINs submitted in the request.
summary.successful / summary.failed	integer	Counts of successful and failed VINs after validation and decode.

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