API Reference

The VIN Doc Vehicle Data API

A developer-first REST API for vehicle history at scale. Create lookups, decode VINs and run bulk jobs over a single base URL, with Bearer auth, signed webhooks and per-key rate limits.

</>https://api.vin-doc.com/v1

Get API access Browse endpoints

On this page

Quick Start

Provision API keys

Sign up and provision a key pair from the dashboard: a sandbox key for integration testing and a production key. Sandbox traffic is free and never consumes billable quota.

Make your first call

Pass your token in the Authorization: Bearer header and GET /v1/vin/{vin}/decode against the base URL https://api.vin-doc.com to confirm connectivity before you create lookups.

Handle the response & webhooks

Decode reads return JSON synchronously; a lookup is async, poll the status endpoint or register a webhook to receive the completed payload as soon as it is ready.

Authentication

All requests are authenticated with a Bearer token in the Authorization header plus an X-Api-Key header over HTTPS. Keys are scoped (sandbox vs production), can be rotated without downtime, and expire 12 months after issuance.

cURL

curl -H "Authorization: Bearer YOUR_API_KEY" \
 -H "X-Api-Key: YOUR_API_KEY" \
 https://api.vin-doc.com/v1/vin/WBA3A5G59DNP26082/decode

Security

Keep keys server-side. Never embed them in client code or query strings, route calls through your backend or a proxy and store secrets in environment variables.

Endpoints

Five v1 endpoints share the base URL https://api.vin-doc.com and a single /v1/lookups vocabulary. All exchange JSON (Content-Type: application/json); POST endpoints expect a JSON body and support idempotency keys.

POST/v1/lookups

Create a lookup

Creates a vehicle lookup. Processing is asynchronous: the response returns a lookup_id prefixed lkp_ with status pending, which transitions to completed (median ~55s). Register a webhook to receive the lookup.completed event.

Parameters

Name	Type	Description
vin	string	17-character ISO 3779 VIN. Required when license_plate is omitted
license_plate	string	License plate. Required when vin is omitted
country	string	ISO 3166-1 alpha-2 country code, for example FR
callback_url	string	HTTPS webhook URL notified when the lookup completes

Example Request

# By VIN
curl -X POST https://api.vin-doc.com/v1/lookups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vin": "WBA3A5G59DNP26082", "country": "FR"}'

# By license plate
curl -X POST https://api.vin-doc.com/v1/lookups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"license_plate": "AB-123-CD", "country": "FR"}'

GET/v1/lookups/{lookup_id}

Retrieve a lookup

Returns the full typed lookup object for a given lookup_id once it has completed, including vehicle, history, inspection and emissions data.

Example Request

curl -X GET https://api.vin-doc.com/v1/lookups/lkp_4a91c2 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Api-Key: YOUR_API_KEY"

GET/v1/lookups/{lookup_id}/status

Get lookup status

Returns the current state of an async lookup, pending, processing, completed or failed, plus a link to the result once ready. Use this when you do not rely on webhooks.

Example Request

curl -X GET https://api.vin-doc.com/v1/lookups/lkp_4a91c2/status \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Api-Key: YOUR_API_KEY"

POST/v1/lookups/batch

Bulk lookups

Queues an array of identifiers (VINs or plates) for parallel processing in a single request, built for fleets and bulk imports. Each identifier is billed and tracked independently; results stream back via the batch.completed webhook.

Example Request

curl -X POST https://api.vin-doc.com/v1/lookups/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"identifiers": ["WBA3A5G59DNP26082", "AB-123-CD"]}'

GET/v1/vin/{vin}/decode

Decode a VIN

Synchronous lookup that decodes an ISO 3779 VIN into manufacturer, model, model year, plant and factory powertrain specs. Ideal for autofilling forms before you create a full lookup.

Example Request

curl -X GET https://api.vin-doc.com/v1/vin/WBA3A5G59DNP26082/decode \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Schema

A completed lookup returns one typed object keyed by lookup_id. vehicle carries decoded specs, history aggregates mileage, accidents, theft and title, and inspection, emissions and meta complete the record.

200 OK

{
  "lookup_id": "lkp_4a91c2",
  "vin": "WBA3A5G59DNP26082",
  "generated_at": "2026-03-12T10:04:00Z",
  "vehicle": { "make": "BMW", "model": "320d", "year": 2019 },
  "history": {
    "mileage": { "value": 142350, "unit": "km", "consistent": true },
    "accidents": { "count": 0 },
    "theft": { "reported": false },
    "title": "clean"
  },
  "inspection": { "passed": true, "date": "2025-09" },
  "emissions": { "class": "Euro 6d" },
  "sources": 8200,
  "meta": { "country": "FR" }
}

Response Fields

Field	Description
`lookup_id`	Unique identifier of the lookup, prefixed lkp_
`vin`	The Vehicle Identification Number that was queried
`generated_at`	ISO 8601 timestamp at which the lookup was generated
`vehicle`	Decoded vehicle object: make, model and year
`history.mileage`	Odometer object: value, unit and consistency flag
`history.accidents`	Accident object: reported count
`history.theft`	Theft object: reported boolean
`history.title`	Title brand status, for example clean
`inspection`	Inspection object: passed boolean and date
`emissions`	Emissions object: class, for example Euro 6d
`sources`	Number of data sources queried for this lookup
`meta.country`	ISO 3166-1 country code the lookup was run for

Error Codes

The API uses conventional HTTP status codes with standard reason phrases. On failure the body contains an error object with a numeric code, a short message and a human-readable detail to speed up debugging.

Code	Message	Description
400	Bad Request	The JSON body is malformed or a required field (vin or license_plate, plus country) is missing.
401	Unauthorized	The Bearer token or X-Api-Key is missing, invalid, expired or has been revoked.
403	Forbidden	The key is valid but lacks the scope or plan entitlement for this endpoint.
404	Not Found	The referenced resource, lookup_id or VIN, does not exist.
429	Too Many Requests	Per-key rate limit exceeded. Inspect the X-RateLimit headers and retry after the reset window.
500	Internal Server Error	An unexpected error occurred upstream. Retry with backoff or contact support if it persists.

Error Response Example

{
  "status": "error",
  "error": {
    "code": 401,
    "message": "Unauthorized",
    "detail": "The provided API key is invalid or has expired."
  }
}

Rate Limiting

Throttling is enforced per API key with a sliding-window algorithm; ceilings scale with your plan and Enterprise keys can be granted dedicated limits. Live counters are returned on every response.

300

Requests / min

50,000

Requests / day

Concurrent

Rate Limit Headers

Each response carries headers so you can track consumption and back off gracefully before hitting a 429.

X-RateLimit-LimitMaximum requests allowed in the current window

X-RateLimit-RemainingRequests still available in the current window

X-RateLimit-ResetUnix timestamp at which the window resets

Build on the VIN Doc API

Request production access or talk to our integration engineers about fleet-scale volume. Sandbox to production is a one-line key swap, no code changes required.

Get API access Talk to engineering

The VIN Doc Vehicle Data API

Provision API keys

Make your first call

Handle the response & webhooks

Authentication

Endpoints

Create a lookup

Parameters

Retrieve a lookup

Get lookup status

Bulk lookups

Decode a VIN

Response Schema

Response Fields

Error Codes

Rate Limiting

Rate Limit Headers

Build on the VIN Doc API

Product

Resources

Company

Legal