---
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"
---

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

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

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

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

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

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

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