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.

Who uses this API

Marketplaces, dealerships, and insurers call this endpoint to inspect title, salvage, odometer, and insurance events before they list, buy, or underwrite a vehicle.

Use cases

B2B

• Marketplaces — listing trust: Surface salvage, title brands, and odometer events so buyers can judge a listing before they inquire.
• Dealerships — acquisition checks: Review junk, salvage, and title history before taking a unit into inventory.
• Insurance — claims and underwriting: Use prior insurance and title activity as context for risk and fraud review.

Parameters

Example

curl -G https://api.carsxe.com/history \
  -d key=YOUR_API_KEY \
  -d vin=WBAFR7C57CC811956

History with lien & theft in one call

Pass lienTheft=true to add a Lien & Theft check for the same VIN. The response keeps every history field above and adds a lienTheft object. The example VIN returns this response for free (trim_data is shortened here).

curl -G https://api.carsxe.com/history \
  -d key=YOUR_API_KEY \
  -d vin=WBAFR7C57CC811956 \
  -d lienTheft=true

The CarsXE SDKs do not pass lienTheft yet. Call it over plain HTTP as shown above.

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.

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.

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.

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.

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.

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.

lienTheft

Present only with lienTheft=true. On success it is the Lien & Theft response body for the same VIN without its input and timestamp fields: success, year, make, model, type, events, and trim_data when the source returns decoded vehicle details. See the Lien & Theft response for every field. With format=xml, characters in trim_data keys that aren't valid in XML element names become _, so Model Year is returned as <Model_Year>.

"lienTheft": {
  "success": true,
  "year": 2017,
  "make": "ACURA",
  "model": "ILX",
  "type": "CAR",
  "events": [
    {
      "date": "",
      "event": "Open Lien",
      "location": "",
      "details_list": [
        "Vehicle is reported to have an open lien on title: Example Bank"
      ]
    }
  ],
  "trim_data": {
    "General": {
      "Model Year": "2017",
      "Make": "ACURA",
      "Model": "ILX",
      "Trim": "Premium Package/Technology Plus Package"
    }
  }
}

When the check returns no record or the lookup fails, the history report is still returned with success: false and a message under lienTheft:

"lienTheft": {
  "success": false,
  "message": "No lien or theft data found for this VIN"
}

When your credit balance covers the history report but not the Lien & Theft charge, the history report is still returned and lienTheft carries the same insufficient-credits body a 402 would:

"lienTheft": {
  "success": false,
  "code": "insufficient_credits",
  "message": "Insufficient credits. Add credits or enable auto-recharge to continue.",
  "billingUrl": "https://carsxe.com/dashboard/billing",
  "credits": { "available": 2, "shortfall": 3, "cost": 5, "remaining": 0 }
}

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.

Billing

Vehicle History is billed per successful call. lienTheft=true adds one Lien & Theft call on top, and only when lien & theft data is actually returned. If the lien & theft lookup finds nothing or fails, or your balance only covers the history report, you pay for the history report only.

Lookups that fail are free: a 404 with no history record, a validation 400, and upstream 502 / 504 failures are never billed. When you send an Idempotency-Key, a retry replays both charges instead of repeating them. See How Billing Units Work for how units are counted across the rest of the API.

Data availability

Errors

See the Errors guide for general error handling guidance.

Common endpoint-specific messages:

• 400 - "Missing vin (vehicle identification number)", "Wrong VIN length, must be 17 characters", or "Invalid VIN" - 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.