VinLink gives developers and business teams programmatic access to vehicle data from a VIN or US license plate. Use the API to retrieve structured vehicle reports including year, make, model, trim, technical specifications, warranty data, MSRP, ACES mapping, and manufacturer recall information.

Whether you are building a vehicle marketplace, service platform, insurance workflow, parts catalog, fleet tool, compliance process, or internal data operation, this guide helps you choose the right VinLink usage pattern and reach the detailed documentation faster.

---

What Can You Do With VinLink?

Use case	Best starting point	Typical user
Decode one VIN into vehicle details	VIN Reports	Developer, product team, operations
Turn a license plate into one or more VINs	Plate-to-VIN Lookup	Business workflow, intake form, mobile app
Get a vehicle report directly from a plate	Plate + Vehicle Report	Dealer tools, marketplaces, insurance workflows
Process many VINs at once	Batch Decoding	Data teams, operations, high-volume users
Embed vehicle data in an app or backend	API Key Authentication	Developers, engineering teams
Generate customer-ready vehicle documents	PDF Reports	Business teams, support teams, customer-facing apps

Choose Your Integration Path

---

Base URL

All current v1 API endpoints use:

https://api.vinlink.com

Reports use the /report path family. Account, authentication, API key, and user-related endpoints are available at the root API level.

Legacy compatibility: legacy service hosts remain available for existing integrations, but new development should use api.vinlink.com.

Authentication Overview

VinLink report endpoints require a JWT bearer token. There are two main authentication patterns: password login for testing and account-level setup, and API key authentication for production applications and automation.

Pattern	Best for	How it works
Password login	Testing, account-level access, initial setup	Exchange account credentials for an access token and refresh token
API key authentication	Production apps, automation, team access	Exchange a scoped API key for a short-lived JWT token

Password Login Flow

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

A successful response includes:

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

Use the access token in report requests:

Authorization: Bearer eyJhbGci...

When the access token expires, use the refresh token to request a new token pair.

Quick Start: Request Your First VIN Report

This example retrieves a BASIC vehicle report as JSON.

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'])")

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

Use this quick start when you want to confirm authentication, report access, JSON delivery, and the API response fields your workflow needs.

VIN Report Products

Report type	Includes	Best for
BASIC	Year, make, model, trim, NHTSA-required fields, ACES mappings	Fast identification, search, catalog matching
BASIC_PLUS	BASIC data plus dimensions, warranty, and MSRP pricing	Listings, intake workflows, richer vehicle records
ENHANCED	BASIC data plus technical specifications and optional equipment	Detailed vehicle pages, service workflows, valuation support
RECALL	BASIC data plus manufacturer recall and safety campaign data	Safety checks, compliance workflows, service outreach

Custom report configurations may be available for teams with specific data requirements. Contact VinLink to discuss your use case.

VIN Report Endpoints

VinLink accepts both GET and POST request patterns.

GET  /report/v1/report/{type}?vin={VIN}
POST /report/v1/report/{type}

Parameters

Parameter	Required	Description
vin	Yes	17-character Vehicle Identification Number
type	Yes	Report product, such as BASIC, BASIC_PLUS, ENHANCED, or RECALL
pdf	No	Use YES to request PDF output
xsl	No	URL of a custom XSL stylesheet for XML transformation
aaia	No	Include AAIA parts mapping. Default is YES

Response Formats

Accept header	Response format
application/json	JSON
text/xml	XML
application/pdf	PDF

Example: JSON VIN Report

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

Example: PDF VIN Report

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

---

License Plate Lookup

VinLink supports US license plate lookup workflows. These are useful when your user, customer, or internal system starts with a plate number and state instead of a VIN.

Raw Plate-to-VIN Lookup

Use this when you only need VINs associated with a plate.

GET  /report/v1/plate/vins?plateState={state}&plateNumber={plate}
POST /report/v1/plate/vins

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

Plate Lookup With Vehicle Report

Use composite report endpoints when you want a plate lookup and vehicle report in one request.

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

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

If multiple VINs are found for the plate, the response may include a composite result covering each matched vehicle.

Batch Decoding

Batch decoding is designed for larger VIN processing jobs. Instead of calling the API one VIN at a time, submit a list of VINs and receive results after processing completes.

• Enrich a large inventory file
• Validate VIN quality before processing
• Process recurring data feeds
• Support operational teams with large vehicle datasets
• Reduce manual lookup work

Batch Workflow

1. Prepare a file or list with one VIN per line.
2. Validate the VINs before processing.
3. Submit the batch job.
4. Optionally provide an email for completion notification.
5. Retrieve or receive the completed results.

The public file workflow supports a text file with one VIN per line and validates the file before processing. Validation returns the count of valid and invalid VINs before charges are applied.

POST /user/batchdecoding
POST /user/batchdecoding/validate

Verify Your Setup Before Making Charged Requests

Before generating reports, use the test endpoint to confirm that your token is valid and your scopes are active.

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

This is a good first diagnostic step when you are setting up a new environment, rotating credentials, or debugging authorization issues.

HTTP Status Codes

Code	Meaning	What to check
200	Report generated successfully	Continue processing the result
400	Missing or invalid VIN, plate, or report type	Check request parameters
401	Missing, expired, or invalid token	Re-authenticate or refresh token
402	Insufficient account balance	Check account funding or pricing
404	VIN, key, or requested resource not found	Confirm identifiers and endpoint path

Supported Vehicle Types

VinLink covers multiple vehicle classes, including passenger cars, light trucks and SUVs, heavy trucks, motorcycles, recreational vehicles, buses, and trailers.

Data availability can vary by vehicle type and report product. For workflows that depend on specific fields, test representative VINs before committing to a production data model.

Pricing and Report Selection

VinLink is a prepaid service. Standard report pricing includes separate products for BASIC, BASIC_PLUS, ENHANCED, RECALL, and Plate2VIN. Volume discount options may be available for customers planning to decode more than 1,000 VINs annually.

Not every workflow needs the deepest report. Use BASIC for fast vehicle identification, BASIC_PLUS when listings or customer workflows need more detail, ENHANCED when technical specifications matter, and RECALL when safety campaign information is the core requirement.

API Keys for Production Use

For production integrations, API keys are usually the safest authentication pattern. They help keep account credentials out of applications and give teams more control over access.

• Name keys by application, service, team, or environment
• Scope keys to specific operations
• Restrict keys by report type
• Limit keys by IP address where practical
• Revoke or rotate keys without changing account credentials

Environment	Suggested key strategy
Development	Separate key with limited report access
Staging	Separate key that mirrors production scopes where practical
Production	Dedicated key with only the required report types
Mobile app	Scoped key with rapid revocation plan
Internal automation	IP-restricted key where possible

Common Implementation Patterns

Frequently Asked Questions

What is the fastest way to test VinLink?

Log in with your account credentials, request a JWT token, and call a BASIC VIN report with JSON as the response format.

Should I use password login or API keys?

Use password login for setup and account-level management. Use API keys for production applications, automation, team workflows, and any integration where credentials need to be scoped, rotated, or revoked independently.

Can I get data from a license plate instead of a VIN?

Yes. VinLink supports US plate lookup using plate number and state. You can request raw VIN matches or use composite endpoints that return a vehicle report from the plate workflow.

Can VinLink return PDF reports?

Yes. VIN report endpoints can return PDF when requested with the appropriate response format.

Can I process many VINs at once?

Yes. Use batch decoding for large VIN lists. VinLink can validate a list before processing and can notify you when the batch is complete.

Which report type should I choose?

Use BASIC for core vehicle identification, BASIC_PLUS for richer business workflows, ENHANCED for technical details and equipment, and RECALL for safety campaign information.

Where is the full API reference?

The full interactive reference is available in Swagger UI at https://api.vinlink.com/swagger-ui/index.html.