Developer Documentation

Vehicle Verification API

Integrate VIN verification, vehicle valuation, and history data into your platform with our simple REST API.

VIN Check

Validate VIN & check import duty

Valuation

Get vehicle market values

History

Full vehicle report

Overview

The Vehicle Verification API provides three core services for integrating vehicle data into your applications:

Available Services

Field	Type	Description
VIN Check	Service	Validate a VIN and retrieve verification details including import duty payment status.
Vehicle Valuation	Service	Retrieve market valuation data for a vehicle, broken down by condition.
Vehicle History	Service	Retrieve a comprehensive vehicle report including ownership, stolen status, market value, sales history, and accident/damage records.

All endpoints require authentication via a service authorization header and accept a VIN as a path parameter.

Authentication

All endpoints require the following header. Authentication is handled using ServiceAPIAuthentication.

Required Headers

Field	Type	Description
X-Service-Authorizationrequired	String	Bearer token (static secret key or temporary session token)

Example Headerhttp

X-Service-Authorization: Bearer YOUR_SECRET_KEY

Environment Modes

The API supports two operational modes. Mode is internally determined from the authenticated request context.

Field	Type	Description
live	Mode	Calls real third-party vehicle data providers
sandbox	Mode	Returns stub/test data for development

💡 Tip: Use sandbox mode during development. No real vehicle data providers are called in sandbox mode.

Getting a Session Token

Before calling any service endpoint, obtain a temporary session token by making a POST request to the /session-token/ endpoint using your private API key.

POST/session-token/

Request Headers

Field	Type	Description
X-API-KEYrequired	String	Bearer YOUR_API_SECRET_KEY

Example Responsejson

{
  "session_token": "eyJ1c2VyX3V1aWQiOiAiYTgzODQ4MWIt...",
  "mode": "sandbox",
  "expires_in": 900
}

Token Flow

API Secret KeyPOST /session-token/session_tokenUse as Bearer in X-Service-Authorization

VIN Check

Validate a VIN and retrieve verification details including import duty payment status.

GET/services/vin-check/{vin}/

Path Parameters

Field	Type	Description
vinrequired	String	Vehicle Identification Number

✅ Successful Response (200)

Field	Type	Description
vin	String	The queried VIN
make	String	Manufacturer name
model	String	Vehicle model
year	Integer	Model year
payment_status	String	Import duty payment status (paid / not_paid)

Response — paidjson

{
  "vin": "1HGCM82633A004352",
  "make": "Honda",
  "model": "Accord",
  "year": 2003,
  "payment_status": "paid"
}

Response — not paidjson

{
  "vin": "1HGCM56706A071917",
  "payment_status": "not_paid"
}

Payment Status Values

Field	Type	Description
paid	Value	Import duty has been paid for this vehicle.
not_paid	Value	Import duty has not been paid for this vehicle.

Vehicle Valuation

Retrieve market valuation data for a vehicle, broken down by condition.

GET/services/vehicle-valuation/{vin}/

Path Parameters

Field	Type	Description
vinrequired	String	Vehicle Identification Number

✅ Successful Response (200)

Field	Type	Description
vin	String	Vehicle Identification Number
market_value	Array	Valuation breakdown by condition

Market Value Object

Field	Type	Description
condition	String	Vehicle condition (Outstanding, Clean, Average, Rough)
trade_in	String	Trade-in value
private_party	String	Private sale value
dealer_retail	String	Dealer retail value

Example Responsejson

{
  "vin": "2T1BR32E75C446393",
  "market_value": [
    { "condition": "Outstanding", "trade_in": "$6,829", "private_party": "$12,153", "dealer_retail": "$15,200" },
    { "condition": "Clean",       "trade_in": "$6,483", "private_party": "$11,473", "dealer_retail": "$14,273" },
    { "condition": "Average",     "trade_in": "$5,906", "private_party": "$10,341", "dealer_retail": "$12,727" },
    { "condition": "Rough",       "trade_in": "$5,157", "private_party": "$8,869",  "dealer_retail": "$10,719" }
  ]
}

Vehicle History

Retrieve a comprehensive vehicle report including ownership, stolen status, market value, sales history, and accident/damage records.

GET/services/vehicle-history/{vin}/

Path Parameters

Field	Type	Description
vinrequired	String	Vehicle Identification Number

Response Sections

Field	Type	Description
ownership_record	Array	Ownership history with post dates and records
stolen_check	Object	Stolen vehicle status and details
market_value	Array	Vehicle valuation by condition
sales_history	Array	Historical sales events
accident_damage_records	Array	Accident and damage history

Example Responsejson

{
  "vin": "2T1BR32E75C446393",
  "ownership_record": [
    { "post_date": "2019-03-14", "owner_record": "Owner 1" },
    { "post_date": "2021-06-20", "owner_record": "Owner 2" }
  ],
  "stolen_check": {
    "is_stolen": true,
    "license_plate": "T45CYP",
    "color": "BLACK",
    "last_known_location": "EAST BRUNSWICK NJ",
    "date_reported": "2021-05-15"
  },
  "market_value": [
    { "condition": "Outstanding", "trade_in": "$6,829", "private_party": "$12,153", "dealer_retail": "$15,200" },
    { "condition": "Clean", "trade_in": "$6,483", "private_party": "$11,473", "dealer_retail": "$14,273" }
  ],
  "sales_history": [
    { "sale_date": "Oct. 7, 2022", "main_price": "$8,398", "currency": "USD", "mileage": 54802, "location": "Brandywine, MD" }
  ],
  "accident_damage_records": [
    { "post_date": "", "accident_record": "" }
  ]
}

Error Handling

Errors are returned in a standardized format via VehicleValidationCustomAPIException.

Error Response Fields

Field	Type	Description
message	String	Error message
description	String	Detailed error description
status_code	Integer	HTTP status code

Example Errorjson

{
  "message": "Invalid VIN",
  "description": "The provided VIN does not match the expected format.",
  "status_code": 400
}

API Summary

POST/session-token/— Obtain temporary session token

GET/services/vin-check/{vin}/— Validate VIN & check import duty status

GET/services/vehicle-valuation/{vin}/— Get market valuation

GET/services/vehicle-history/{vin}/— Full vehicle report

Need help integrating?

Our developer support team is ready to assist you.

vehiclerecordsproject@gmail.com