Docs & Examples

VinLink API v1 Documentation

The VinLink API gives your application programmatic access to comprehensive vehicle data — decoded from a 17-character VIN or a US license plate number. Reports are available in JSON, XML, and PDF formats and cover everything from basic Year/Make/Model/Trim through full technical specifications, warranty data, and manufacturer recall information.

The full interactive reference with request/response schemas is available in our Swagger UI:
https://api.vinlink.com/swagger-ui/index.html

Base URL

All v1 endpoints are served from a single host:

https://api.vinlink.com

The Reports Service lives under the /report prefix; account and authentication endpoints are at the root.

Legacy compatibility: The previous service.vinlink.com and service-ba.vinlink.com endpoints remain active for existing integrations. New development should target api.vinlink.com, which consolidates all services in one place and adds plate-to-VIN, batch decoding, and a modern authentication layer.

Authentication

All report endpoints require a JWT Bearer token in the Authorization header. Obtain one by logging in with your VinLink credentials — or, for embedded applications, by exchanging an API key. API keys can be scoped, revoked individually, and rotated without touching your account password — ideal for mobile clients, server-side integrations, and automation workflows.

Step 1 — Log In

curl -X POST https://api.vinlink.com/user/login \
  -H "Content-Type: application/json" \
  -d '{
    "login": "your@email.com",
    "password": "yourpassword"
  }'

A successful response returns an accessToken (short-lived) and a refreshToken (long-lived):

{
  "accessToken": "eyJhbGci...",
  "refreshToken": "eyJhbGci...",
  "tokenType": "Bearer",
  "expiresIn": 3600
}

Step 2 — Use the Token

Pass the access token in every API request:

Authorization: Bearer eyJhbGci...

Refreshing Tokens

When the access token expires, exchange the refresh token for a new pair without re-entering credentials. Token rotation is enforced — the old refresh token is invalidated immediately.

curl -X POST https://api.vinlink.com/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "eyJhbGci..."}'

Quick Start — Your First VIN Report

# 1. Log in and capture the access token
TOKEN=$(curl -s -X POST https://api.vinlink.com/user/login \
  -H "Content-Type: application/json" \
  -d '{"login":"your@email.com","password":"yourpassword"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['accessToken'])")

# 2. Decode a VIN — returns JSON
curl "https://api.vinlink.com/report/v1/report/BASIC?vin=1HGBH41JXMN109186" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

VIN Reports

Endpoint

GET  https://api.vinlink.com/report/v1/report/{type}?vin={VIN}
POST https://api.vinlink.com/report/v1/report/{type}

Both GET (query parameters) and POST (form parameters) are accepted. The {type} path variable selects the report product.

Parameters

Parameter	Required	Description
`vin`	Yes	17-character Vehicle Identification Number
`type` (path)	Yes	Report product — see table below
`pdf`	No	`YES` to receive a PDF instead of XML/JSON
`xsl`	No	URL of a custom XSL stylesheet for XML transformation
`aaia`	No	Include AAIA parts mapping (`YES`/`NO`, default `YES`)

Report Types

Type	Contents
`BASIC`	Year, Make, Model, Trim (YMMT), NHTSA required fields, ACES mappings
`BASIC_PLUS`	BASIC + vehicle dimensions, warranty, and MSRP pricing
`ENHANCED`	BASIC + full technical specifications and optional equipment
`RECALL`	BASIC + manufacturer recall and safety campaign data

Need something specific? We can create custom report configurations tailored to your data requirements. Contact us to discuss your use case.

To retrieve the full product catalog with current pricing for your account:

curl "https://api.vinlink.com/report/v1/report/types?category=vinlink" \
  -H "Authorization: Bearer $TOKEN"

Response Format

Use the Accept header to select the response format:

Accept header	Format
`application/json`	JSON
`text/xml` (default)	XML
`application/pdf`	PDF

Examples

# JSON report
curl "https://api.vinlink.com/report/v1/report/BASIC?vin=1HGBH41JXMN109186" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

# XML report (default)
curl "https://api.vinlink.com/report/v1/report/ENHANCED?vin=1HGBH41JXMN109186" \
  -H "Authorization: Bearer $TOKEN"

# PDF download
curl "https://api.vinlink.com/report/v1/report/BASIC_PLUS?vin=1HGBH41JXMN109186" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/pdf" \
  --output report.pdf

HTTP Status Codes

Code	Meaning
`200`	Report generated successfully
`400`	Missing or invalid VIN / report type
`401`	Missing or invalid JWT token
`402`	Insufficient account balance
`404`	VIN not found in the database

License Plate Lookup (Plate-to-VIN)

VinLink now supports US license plate lookups. Plate-to-VIN queries are a two-charge operation: one charge for the plate lookup itself (PLATE2VIN product) and, optionally, a second charge per VIN for the vehicle report.

Raw Plate Lookup — VINs Only

GET  https://api.vinlink.com/report/v1/plate/vins?plateState={state}&plateNumber={plate}
POST https://api.vinlink.com/report/v1/plate/vins

Returns all VINs registered to the plate, along with associated recall data, charged as the PLATE2VIN product.

# JSON response
curl "https://api.vinlink.com/report/v1/plate/vins?plateState=FL&plateNumber=ABC1234" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Plate + Vehicle Report (Composite)

These endpoints combine the plate lookup and a full vehicle report in a single call:

Endpoint	Report included
`/v1/report/plate_basic`	BASIC report for each VIN found
`/v1/report/plate_basic_plus`	BASIC_PLUS report for each VIN found

# Plate lookup + BASIC_PLUS report, JSON
curl "https://api.vinlink.com/report/v1/report/plate_basic_plus?plateState=CA&plateNumber=8ABC234" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Parameters are the same as for VIN reports, substituting plateState and plateNumber for vin. If multiple VINs are found for a plate, the response contains a composite document covering all of them. VINs for which the report charge fails appear in the response with error="No funds".

Pricing for plate and lookup products can be retrieved from:

curl "https://api.vinlink.com/report/v1/report/types?category=plate&category=lookup" \
  -H "Authorization: Bearer $TOKEN"

Batch Decoding

For large-scale processing, VinLink supports asynchronous batch decoding. Submit a list of VINs via POST /user/batchdecoding and receive results when processing is complete. An optional email parameter can be used to receive a notification when the batch is ready.

To validate a list of VINs before submitting a batch job:

POST /user/batchdecoding/validate

Full batch decoding details are documented in the Swagger UI under the Batch Decoding section.

Verifying Your Setup

Use the test endpoint to confirm that your token is valid and see which scopes are active before making charged requests:

curl https://api.vinlink.com/report/v1/report/test \
  -H "Authorization: Bearer $TOKEN"

Supported Vehicle Types

VinLink covers a broad spectrum of vehicle classes:

Passenger Cars
Light Trucks & SUVs
Heavy Trucks
Motorcycles
Recreational Vehicles (RVs)
Buses & Trailers

Data availability varies by vehicle type and report product. Not all report types are available for all vehicle classes.

Full API Reference

The Swagger UI at https://api.vinlink.com/swagger-ui/index.html contains the complete, interactive reference for all endpoints — including request schemas, response models, enumerated values, and the ability to execute calls directly against the live API. Use the group selector in the top-right corner to switch between the Public API (account management) and the VinLink Reports Service (decoding and plate lookup).

Support

For questions or to request access, contact us at administration@vinlink.com or use the contact form on our website.