Retrieve a vehicle history report by VIN. The /history endpoint returns title records, brand records, junk and salvage events, insurance information, VIN change indicators, odometer readings, and historical title activity when available.
History data depends on the records available from reporting sources and jurisdictions. Most integrations should treat the response as a set of optional record groups and handle missing or empty arrays gracefully.
Parameters
| Parameter | Required | Description |
|---|---|---|
vin | Yes | The 17-character vehicle identification number |
key | Yes | Your CarsXE API key |
format | No | json (default) or xml |
Example
Get vehicle history
Response
Top-level shape
Click any object or array to expand it and see sample data. For the full interactive reference, try it live in the API Reference.
All response fields are optional. Empty or missing arrays mean CarsXE did not receive that record group for the VIN.
junkAndSalvageInformation
Junk and salvage records describe events reported by junk yards, salvage yards, recyclers, auctions, or similar reporting entities. These records are useful for identifying total-loss, salvage, export, or disposition activity.
- Name
ReportingEntityAbstract- Type
- object
- Description
Reporting entity details, such as category, entity name, location, phone number, and contact email when available.
- Name
VehicleObtainedDate- Type
- string
- Description
Date the reporting entity obtained or recorded the vehicle. Example:
"2016-12-06T00:00:00.000Z".
- Name
VehicleDispositionText- Type
- string
- Description
Reported disposition for the vehicle. Example:
"TO BE DETERMINED".
- Name
VehicleIntendedForExportCode- Type
- string
- Description
Export intent flag from the source record. Example:
"Y"or"N".
Common fields inside ReportingEntityAbstract include ReportingEntityCategoryCode, IdentificationID, ReportingEntityCategoryText, EntityName, LocationCityName, LocationStateUSPostalServiceCode, TelephoneNumberFullID, and ContactEmailID.
insuranceInformation
Insurance records describe information reported by insurance carriers or related entities. Depending on the source record, this can include the reporting entity and the date the vehicle was obtained or reported.
- Name
ReportingEntityAbstract- Type
- object
- Description
Insurance or reporting entity details, including name and location when available.
- Name
VehicleObtainedDate- Type
- string
- Description
Date associated with the insurance record.
brandsInformation
Brand records describe labels applied to the title or vehicle record, such as salvage, rebuilt, flood damage, collision, prior taxi, or other jurisdiction-defined brands. brandsRecordCount gives the number of brand records returned.
- Name
name- Type
- string
- Description
Normalized brand name when the source provides one. Example:
"Salvage".
- Name
code- Type
- string
- Description
Source or brand code when available.
- Name
description- Type
- string
- Description
Human-readable explanation of the brand.
Brand payloads can include additional source-specific fields.
currentTitleInformation
Current title records describe the latest title information available for the VIN. Some records also include nested historical title details.
- Name
TitleIssuingAuthorityName- Type
- string
- Description
Jurisdiction or state that issued the title. Example:
"CA".
- Name
TitleIssueDate.Date- Type
- string
- Description
Title issue date as an ISO timestamp.
- Name
VehicleOdometerReadingMeasure- Type
- string
- Description
Odometer reading from the title record. Values may be zero-padded.
- Name
VehicleOdometerReadingUnitCode- Type
- string
- Description
Odometer unit code. Example:
"M"for miles.
- Name
HistoricTitleAbstract- Type
- array
- Description
Nested historical title records when included by the source.
historyInformation
Historical title records list prior title activity for the VIN. Use this array to build a title timeline, compare title jurisdictions, and inspect odometer readings across title events.
- Name
VehicleIdentification.IdentificationID- Type
- string
- Description
VIN attached to the historical title record.
- Name
TitleIssuingAuthorityName- Type
- string
- Description
Jurisdiction or state that issued the title.
- Name
TitleIssueDate.Date- Type
- string
- Description
Historical title issue date as an ISO timestamp.
- Name
VehicleOdometerReadingMeasure- Type
- string
- Description
Odometer reading recorded for the historical title.
- Name
VehicleOdometerReadingUnitCode- Type
- string
- Description
Odometer unit code. Example:
"M"for miles.
vinChanged
vinChanged is a boolean indicator for whether the source reports a VIN change. A value of false means no VIN change was reported in the available data.
How to read dates and odometer values
Dates are returned as ISO timestamps. If your UI only needs the calendar date, display the date portion before T.
Odometer readings may be returned as zero-padded strings, such as "000024806". Parse them as numbers only after preserving the original value if you need to show source data exactly.
VehicleOdometerReadingUnitCode identifies the odometer unit. The examples on this page use "M" for miles.
Data availability
Vehicle history depends on reporting sources, jurisdiction coverage, and update timing. Empty or missing arrays mean no available records were returned from the source for that group; they are not a guarantee that no event ever occurred.
Errors
See the Errors guide for general error handling guidance.
| Status | When it happens |
|---|---|
400 | Missing VIN or wrong VIN length |
401 | Missing or invalid API key |
403 | This API key has been blocked for the History API |
404 | No history data found for this VIN |
Common endpoint-specific messages:
- 400 -
"Missing vin (vehicle identification number)"or"Wrong VIN length, must be 17 characters"- fix the input before retrying. - 403 -
"This API key has been blocked, please contact support if you believe this is an error."- contact support if the key should have access. - 404 - no history report is available for the VIN.