---
title: "Vehicle History"
description: "Retrieve comprehensive history reports including title records, salvage events, and insurance data."
canonical_url: "https://docs.carsxe.com/docs/products/vehicle-history"
markdown_url: "https://docs.carsxe.com/docs/products/vehicle-history.md"
last_updated: "1980-01-01"
x_farming_labs_generated_preamble: true
agent:
  task: "Fetch CarsXE vehicle history events for a VIN."
  outcome: "A Vehicle History request returns the documented successful vehicle-data response for the supplied input."
  prerequisites:
    - "A valid CarsXE API key with access to this endpoint."
    - "The vehicle identifier or request inputs required by the Vehicle History example."
  verification:
    - "Run one documented Vehicle History request and confirm the response is successful and contains the fields described on this page."
  failureModes:
    - symptom: "The Vehicle History request is rejected or does not return the expected data."
      resolution: "Check the API key, plan access, supported input format, and the returned status code against the error guide before retrying."
---

# Vehicle History
URL: /docs/products/vehicle-history
LLM index: /llms.txt
Description: Retrieve comprehensive history reports including title records, salvage events, and insurance data.
Related: /docs/products, /docs/get-started

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Fetch CarsXE vehicle history events for a VIN.
Outcome: A Vehicle History request returns the documented successful vehicle-data response for the supplied input.

### Prerequisites

- A valid CarsXE API key with access to this endpoint.
- The vehicle identifier or request inputs required by the Vehicle History example.

### Verification

- Run one documented Vehicle History request and confirm the response is successful and contains the fields described on this page.

### Failure Modes

- The Vehicle History request is rejected or does not return the expected data. — Recovery: Check the API key, plan access, supported input format, and the returned status code against the error guide before retrying.
<!-- farming-labs:agent-contract:end -->

Task: Fetch CarsXE vehicle history events for a VIN.
Related: /docs/products/vehicle-history, /docs/products/ownership, /docs/get-started

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

| Parameter | Required | Description |
|---|---|---|
| `vin` | Yes | The 17-character vehicle identification number |
| `key` | Yes | Your CarsXE API key |
| `format` | No | `json` (default) or `xml` |
| `lienTheft` | No | `true` or `1` attaches a [Lien & Theft](/docs/products/lien-theft) check for the same VIN under `lienTheft`. Billed as one extra Lien & Theft call; see [Billing](#billing). |

## Example

<CodeGroup title="Get vehicle history" tag="GET" label="/history">

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

```js
import { CarsXE } from "carsxe-api";

const carsxe = new CarsXE("YOUR_API_KEY");
const vin = "WBAFR7C57CC811956";

try {
  const history = await carsxe.history({ vin });
  console.log(history);
} catch (error) {
  console.error(error);
}
```

```python
import asyncio
from carsxe_api import CarsXE

carsxe = CarsXE("YOUR_API_KEY")
vin = "WBAFR7C57CC811956"

try:
    history = asyncio.run(carsxe.history({"vin": vin}))
    print(history)
except Exception as e:
    print(f"Error: {e}")
```

```php
<?php
require_once __DIR__ . '/vendor/autoload.php';
use CarsxeDeveloper\Carsxe\Carsxe;

$carsxe = new Carsxe("YOUR_API_KEY");
$vin = "WBAFR7C57CC811956";

try {
    $history = $carsxe->history(["vin" => $vin]);
    print_r($history);
} catch (Exception $error) {
    echo "Error: " . $error->getMessage();
}
```

```ruby
require "carsxe"

carsxe = Carsxe::CarsXE.new(api_key: "YOUR_API_KEY")
vin = "WBAFR7C57CC811956"

begin
  history = carsxe.history("vin" => vin)
  puts history
rescue StandardError => error
  puts "Error: #{error.message}"
end
```

```go
package main

import (
	"fmt"
	"github.com/carsxe/carsxe-go-package"
)

func main() {
	client := carsxe.New("YOUR_API_KEY")
	vin := "WBAFR7C57CC811956"
	history := client.History(map[string]string{"vin": vin})
	fmt.Println(history)
}
```

```java
import io.github.carsxe.CarsXE;
import java.util.Map;
import java.util.HashMap;

public class Main {
    public static void main(String[] args) {
        CarsXE carsxe = new CarsXE("YOUR_API_KEY");
        Map<String, String> params = new HashMap<>();
        params.put("vin", "WBAFR7C57CC811956");

        try {
            Map<String, Object> history = carsxe.history(params);
            System.out.println(history);
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}
```

```swift
import carsxe

let carsxe = CarsXE(apiKey: "YOUR_API_KEY")
let vin = "WBAFR7C57CC811956"

do {
    let history = try carsxe.history(["vin": vin])
    print(history)
} catch {
    print("Error: \(error)")
}
```

```csharp
using carsxe;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        CarsXE carsxe = new CarsXE("YOUR_API_KEY");
        string vin = "WBAFR7C57CC811956";

        try
        {
            var history = await carsxe.History(new Dictionary<string, string> { { "vin", vin } });
            Console.WriteLine(history);
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}
```

```bash {{ title: "Response" }}
{
  "success": true,
  "vin": "WBAFR7C57CC811956",
  "junkAndSalvageInformation": [
    {
      "ReportingEntityAbstract": {
        "ReportingEntityCategoryText": "Junk and Salvage",
        "EntityName": "Copart, Inc.",
        "LocationCityName": "Dallas",
        "LocationStateUSPostalServiceCode": "TX"
      },
      "VehicleObtainedDate": "2016-12-06T00:00:00.000Z",
      "VehicleDispositionText": "TO BE DETERMINED",
      "VehicleIntendedForExportCode": "N"
    }
  ],
  "insuranceInformation": [],
  "brandsRecordCount": 2,
  "brandsInformation": [
    {
      "name": "Salvage",
      "code": "50",
      "description": "Vehicle branded salvage"
    }
  ],
  "vinChanged": false,
  "currentTitleInformation": [
    {
      "TitleIssuingAuthorityName": "CA",
      "TitleIssueDate": { "Date": "2015-06-11T00:00:00.000Z" },
      "VehicleOdometerReadingMeasure": "000024806",
      "VehicleOdometerReadingUnitCode": "M"
    }
  ],
  "historyInformation": [
    {
      "VehicleIdentification": {
        "IdentificationID": "WBAFR7C57CC811956"
      },
      "TitleIssuingAuthorityName": "CA",
      "TitleIssueDate": { "Date": "2015-04-16T00:00:00.000Z" },
      "VehicleOdometerReadingMeasure": "000024806",
      "VehicleOdometerReadingUnitCode": "M"
    }
  ]
}
```

</CodeGroup>

## History with lien & theft in one call

Pass `lienTheft=true` to add a [Lien & Theft](/docs/products/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).

<CodeGroup title="Get vehicle history with lien & theft" tag="GET" label="/history">

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

```bash {{ title: "Response" }}
{
  "success": true,
  "vin": "WBAFR7C57CC811956",
  "junkAndSalvageInformation": [
    {
      "ReportingEntityAbstract": {
        "ReportingEntityCategoryText": "Junk and Salvage",
        "EntityName": "Copart, Inc.",
        "LocationCityName": "Dallas",
        "LocationStateUSPostalServiceCode": "TX"
      },
      "VehicleObtainedDate": "2016-12-06T00:00:00.000Z",
      "VehicleDispositionText": "TO BE DETERMINED",
      "VehicleIntendedForExportCode": "N"
    }
  ],
  "insuranceInformation": [],
  "brandsRecordCount": 2,
  "brandsInformation": [
    {
      "name": "Salvage",
      "code": "50",
      "description": "Vehicle branded salvage"
    }
  ],
  "vinChanged": false,
  "currentTitleInformation": [
    {
      "TitleIssuingAuthorityName": "CA",
      "TitleIssueDate": { "Date": "2015-06-11T00:00:00.000Z" },
      "VehicleOdometerReadingMeasure": "000024806",
      "VehicleOdometerReadingUnitCode": "M"
    }
  ],
  "historyInformation": [
    {
      "VehicleIdentification": {
        "IdentificationID": "WBAFR7C57CC811956"
      },
      "TitleIssuingAuthorityName": "CA",
      "TitleIssueDate": { "Date": "2015-04-16T00:00:00.000Z" },
      "VehicleOdometerReadingMeasure": "000024806",
      "VehicleOdometerReadingUnitCode": "M"
    }
  ],
  "lienTheft": {
    "success": true,
    "year": 2012,
    "make": "BMW",
    "model": "535i",
    "type": "CAR",
    "events": [
      {
        "date": "07/01/2015",
        "event": "Open Lien",
        "location": "CA",
        "details_list": [
          "Vehicle is reported to have an open lien on title: Example Bank"
        ]
      }
    ],
    "trim_data": {
      "General": {
        "Model Year": "2012",
        "Make": "BMW",
        "Model": "535i",
        "Series": "5-Series",
        "Body Class": "Sedan/Saloon"
      }
    }
  }
}
```

</CodeGroup>

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

## Response

### Top-level shape

<VehicleHistoryTopLevelShape />

Click any object or array to expand it and see sample data. For the full interactive reference, try it live in the [API Reference](/api-reference/history/vehicle-history).

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.

<Properties>
  <Property name="ReportingEntityAbstract" type="object">
    Reporting entity details, such as category, entity name, location, phone number, and contact email when available.
  </Property>
  <Property name="VehicleObtainedDate" type="string">
    Date the reporting entity obtained or recorded the vehicle. Example: `"2016-12-06T00:00:00.000Z"`.
  </Property>
  <Property name="VehicleDispositionText" type="string">
    Reported disposition for the vehicle. Example: `"TO BE DETERMINED"`.
  </Property>
  <Property name="VehicleIntendedForExportCode" type="string">
    Export intent flag from the source record. Example: `"Y"` or `"N"`.
  </Property>
</Properties>

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.

<Properties>
  <Property name="ReportingEntityAbstract" type="object">
    Insurance or reporting entity details, including name and location when available.
  </Property>
  <Property name="VehicleObtainedDate" type="string">
    Date associated with the insurance record.
  </Property>
</Properties>

### 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.

<Properties>
  <Property name="name" type="string">
    Normalized brand name when the source provides one. Example: `"Salvage"`.
  </Property>
  <Property name="code" type="string">
    Source or brand code when available.
  </Property>
  <Property name="description" type="string">
    Human-readable explanation of the brand.
  </Property>
</Properties>

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.

<Properties>
  <Property name="TitleIssuingAuthorityName" type="string">
    Jurisdiction or state that issued the title. Example: `"CA"`.
  </Property>
  <Property name="TitleIssueDate.Date" type="string">
    Title issue date as an ISO timestamp.
  </Property>
  <Property name="VehicleOdometerReadingMeasure" type="string">
    Odometer reading from the title record. Values may be zero-padded.
  </Property>
  <Property name="VehicleOdometerReadingUnitCode" type="string">
    Odometer unit code. Example: `"M"` for miles.
  </Property>
  <Property name="HistoricTitleAbstract" type="array">
    Nested historical title records when included by the source.
  </Property>
</Properties>

### 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.

<Properties>
  <Property name="VehicleIdentification.IdentificationID" type="string">
    VIN attached to the historical title record.
  </Property>
  <Property name="TitleIssuingAuthorityName" type="string">
    Jurisdiction or state that issued the title.
  </Property>
  <Property name="TitleIssueDate.Date" type="string">
    Historical title issue date as an ISO timestamp.
  </Property>
  <Property name="VehicleOdometerReadingMeasure" type="string">
    Odometer reading recorded for the historical title.
  </Property>
  <Property name="VehicleOdometerReadingUnitCode" type="string">
    Odometer unit code. Example: `"M"` for miles.
  </Property>
</Properties>

### 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](/docs/products/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](/docs/products/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>`.

```json
"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`:

```json
"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:

```json
"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`, upstream `502` / `504` failures, and `503` temporarily-unavailable responses are never billed. When you send an `Idempotency-Key`, a retry replays both charges instead of repeating them. See [How Billing Units Work](/docs/guides/billing-units) for how units are counted across the rest of the API.

## Data availability

<Note>
  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.
</Note>

## Errors

See the [Errors guide](/docs/guides/errors) for general error handling guidance.

| Status | When it happens |
|---|---|
| `400` | Missing, incorrectly sized, or invalid VIN |
| `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 |
| `500` | Internal error or non-retryable upstream authentication failure |
| `502` | Upstream history provider returned an error; response includes `retryable: true` and `Retry-After` |
| `503` | Temporarily unavailable; not billed. Response includes `code: "temporarily_unavailable"`, `retryable: true`, and `Retry-After`; retry after that many seconds |
| `504` | Upstream history provider timed out; response includes `retryable: true` and `Retry-After` |

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.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).
