You need to tell drivers and buyers whether a vehicle has open safety recalls, and you want to do it reliably from a VIN with one fast API call. By the end of this guide, you’ll be able to call the Vehicle API VIN Recall Check endpoint, parse the recall campaigns from NHTSA, handle US-only coverage, and ship production-ready error handling, caching, and quota awareness.
What this endpoint returns and when to use it
The VIN Recall Check returns official US-market safety recall campaigns as published by NHTSA. Results are matched by make, model, and year derived from the VIN. The response does not indicate whether a specific car has already been repaired; it reports relevant campaigns for that vehicle configuration and model year.
Key coverage facts to plan around:
- VIN decoding works worldwide, with the most complete detail for US-market vehicles.
- Recalls, owner complaints, and NCAP crash ratings are US-market only and are matched by make + model + year.
- For this endpoint, a valid non-US VIN returns an error with code
coverage_us_only(HTTP 422). - Dutch license plates are sourced from RDW open data and never include a VIN; use VIN-based endpoints for recall data.
- This is not a vehicle history report; it does not include title, accident, or ownership history.
If you are building dealer tools, marketplaces, fleet, insurance, or AI agent workflows and you need trustworthy recall data tied to a VIN, this endpoint is the shortest path to shipping.
Endpoint and authentication
Base URL: https://vehicles-api.com/api/v1
Endpoint: GET /vin/recalls
Query parameters:
vin(required): a 17-character VIN.
Auth: send your key in one of the following headers:
X-API-Key: YOUR_API_KEY(recommended)Authorization: Bearer YOUR_API_KEY(also supported)
Every response is returned as an envelope with:
status:successorerrorsource: the upstream data source (e.g.,nhtsa) whensuccessdata: the recall payload whensuccesserror.codeanderror.messagewhenerror
Read the API reference for request/response details in the Documentation. For server and agent integrations, see MCP.
Quickstart: curl and sample response
Below is the official docs example. The control VIN 1HGCM82633A004352 decodes to a 2003 HONDA Accord. Counts and campaigns change over time as NHTSA updates its datasets; use this example to wire up your parser.
curl "https://vehicles-api.com/api/v1/vin/recalls?vin=1HGCM82633A004352" -H "X-API-Key: YOUR_API_KEY"Sample JSON response (NHTSA source):
{
"status": "success",
"source": "nhtsa",
"data": {
"vin": "1HGCM82633A004352",
"year": 2003,
"make": "HONDA",
"model": "Accord",
"coverage": "us",
"count": 24,
"recalls": [
{
"campaign": "19V182000",
"component": "AIR BAGS:FRONTAL:DRIVER SIDE:INFLATOR MODULE",
"received": "2019-03-06",
"summary": "Replacement driver air bag inflator may explode.",
"consequence": "Sharp metal fragments may strike occupants.",
"remedy": "Dealers will replace the inflator, free of charge."
}
]
}
}Fields you will actually use
The outer envelope lets you branch logic early:
status: check forsuccessbefore readingdata. On errors, useerror.codeanderror.message.source: the upstream authority; for this endpoint it will benhtsaon success.
The data object contains recall facts you’ll surface in UI or downstream systems:
vin: the VIN you queried. Useful for logging and cache keys.year,make,model: normalized identifiers from VIN decoding used to match to campaigns.coverage: will beusfor valid US coverage. For non-US VINs, this endpoint returns an error with codecoverage_us_only.count: integer number of recall campaigns matched for the vehicle configuration.recalls: array of campaigns with:campaign: NHTSA campaign identifier, e.g.,19V182000.component: the component/system affected.received: campaign publication date in YYYY-MM-DD (NHTSA date; treat as UTC date-only).summary,consequence,remedy: short texts safe for user-facing display.
Nullability: some campaigns can omit one or more fields in the upstream source; treat missing texts or dates as null and render fallbacks in UI (“Details not provided”). Always code defensively for potentially absent fields inside each recall object.
Implement it in Python
The snippet below calls the same endpoint, checks for errors, and prints a compact recall summary suitable for console logs or audit trails.
import os
import requests
API_KEY = os.getenv("VEHICLES_API_KEY", "YOUR_API_KEY")
BASE_URL = "https://vehicles-api.com/api/v1"
def get_recalls(vin: str) -> dict:
url = f"{BASE_URL}/vin/recalls"
headers = {
"X-API-Key": API_KEY
# Or: "Authorization": f"Bearer {API_KEY}"
}
resp = requests.get(url, params={"vin": vin}, headers=headers, timeout=20)
data = resp.json()
# Vehicle API always returns an envelope with status / data or status / error
if data.get("status") != "success":
# Bubble up the API error in a structured way
err = data.get("error", {})
code = err.get("code", "unknown_error")
msg = err.get("message", "Request failed")
raise RuntimeError(f"VIN recall check failed [{code}]: {msg}")
return data
def summarize_recalls(enveloped: dict) -> None:
src = enveloped.get("source")
payload = enveloped.get("data", {})
vin = payload.get("vin")
year = payload.get("year")
make = payload.get("make")
model = payload.get("model")
coverage = payload.get("coverage")
count = payload.get("count", 0)
print(f"Source={src} VIN={vin} {year} {make} {model} coverage={coverage} campaigns={count}")
for i, r in enumerate(payload.get("recalls", []), start=1):
cid = r.get("campaign")
comp = r.get("component")
received = r.get("received")
summary = r.get("summary")
remedy = r.get("remedy")
print(f" {i}. {cid} | {comp} | {received}")
if summary:
print(f" - Summary: {summary}")
if remedy:
print(f" - Remedy: {remedy}")
if __name__ == "__main__":
vin = "1HGCM82633A004352" # 2003 HONDA Accord (docs control VIN)
try:
env = get_recalls(vin)
summarize_recalls(env)
except Exception as e:
print(str(e))Swap in your user’s VIN and wire the output to your UI or policy rules. Always check the top-level status before reading data. If you are implementing retries, retry only on transport errors or 5xx, not on application-level errors like coverage_us_only.
Error handling, coverage, and nulls
This endpoint follows a consistent error envelope. Plan for these behaviors:
- US-only coverage: if you send a valid non-US VIN, you will receive an error with
status: "error",error.code: "coverage_us_only", and HTTP 422. For global apps, short-circuit UI with a clear message (“NHTSA recalls are US-only for this VIN”). - Authentication and quota: when the key is missing, invalid, or the account has exceeded limits, the API returns an error envelope with
status: "error". Don’t assume an HTTP 200 on failures; always read the top-levelstatus. - Null fields: upstream records can omit
component,consequence, orremedy. Implement robust null checks.
For plan limits, rate limits, and usage monitoring, see the Documentation. Pricing starts at $19/month for Starter, and every plan includes a 7-day free trial.
Performance, caching, and quotas
Production apps should minimize repeat calls for the same VIN:
- Cache key: VIN + endpoint + source version. For recalls, a simple key of
vin:recalls:{VIN}works. Include a metadata field for thesource(e.g.,nhtsa). - TTL: recalls do not change minute-to-minute. A TTL of 12–24 hours is a practical default; refresh on user demand for critical workflows.
- Staleness strategy: stale-while-revalidate allows instant UI with a background refresh. Keep a
last_checked_attimestamp in your store. - Error caching: cache negative responses like
coverage_us_onlywith a shorter TTL (e.g., 1–6 hours) to avoid needless retries for non-US VINs.
Downstream quotas and rate limits are plan-specific. Implement exponential backoff for 429/5xx and meter concurrency in batch jobs. If you are building an agent or tool that may fan out across VINs, consider a queue with concurrency controls to stay within your monthly allotment.
How this data fits with other Vehicle API capabilities
Recall checks are one of several US-market safety datasets exposed by the API, alongside owner complaints and NCAP ratings. VIN decoding works worldwide and powers the make/model/year used to match against US recall campaigns. Dutch license plate lookups from RDW do not include a VIN, so you cannot use a plate directly for recall queries here.
If you are building AI agents or automations, the same recall lookup is available via the MCP server at MCP. That enables tool usage in LLM runtimes with the same authentication and response envelope semantics.
Designing your UI and workflows
Effective recall presentation balances clarity and brevity. A pattern that works well:
- Header: “Safety recalls for 2003 HONDA Accord (VIN ending 4352)”
- Badge:
countcampaigns fromsource(NHTSA) - List items: one per
recalls[]withcampaign,component,received - Expandable details:
summary,consequence,remedy - Disclaimer: “US-market safety campaigns matched by make/model/year. This does not confirm whether a specific vehicle was repaired.”
For internal tools (dealer ops, fleet safety, underwriting), consider alerting when count > 0 and persisting the campaign IDs you’ve surfaced to avoid re-notifying users on unchanged results.
Security and auditing tips
- Do not log full API keys. Use environment variables and rotate regularly.
- Log the request VIN,
status, and returnedcountto support compliance and support tickets. - Version your parser against the response envelope (
status,source,data) so non-breaking field additions inrecalls[]won’t break your code.
Troubleshooting playbook
- Got
status=errorwithcoverage_us_only? You’re querying a non-US VIN against a US-only recalls dataset. Short-circuit and skip retries. - Getting empty or partial
recalls[]? Not all campaigns have all text fields; render what’s available and provide a link to your support flow if details are missing. - Throttled or quota exceeded? Space out batch jobs, use caching, and consult plan limits in the Documentation.
End-to-end flow checklist
- Input validation: ensure a 17-character VIN before calling the API.
- Call GET
/vin/recallswithX-API-Keyor Bearer token. - Check
status. Onsuccess, readsourceanddata; onerror, branch byerror.code. - Persist
vin,year,make,model,count, andrecalls[]campaign IDs. - Cache results with a daily TTL and stale-while-revalidate. Cache
coverage_us_onlywith a shorter TTL. - Surface user-facing messaging that recalls are US-market and do not indicate repair completion.
FAQs
Does the VIN Recall Check say whether this specific car has been repaired?
No. It returns the official US recall campaigns matched by make, model, and year. It does not track individual repair completion.
What happens if I query a non-US VIN?
This endpoint is US-market only. A valid non-US VIN returns status: "error" with error.code: "coverage_us_only" and HTTP 422.
Do Dutch license plates include a VIN I can use here?
No. RDW open data for Dutch plates does not include a VIN. Use VIN-based endpoints when you need recall data.
What are the rate limits and monthly quota?
They depend on your plan. Every plan includes a 7-day free trial; check the plan and usage details in the Documentation.
Is there an MCP tool for this endpoint?
Yes. You can access the same capability through the MCP server at MCP for agent integrations.
Start building with the VIN Recall Check today. Every plan has a 7-day free trial and the Starter plan is $19/month. Create your API key here: Register. For more product context, visit vehicles-api.com and wire it up using the Documentation.
