Recalls covers four endpoints that answer the same question from different starting points. Use Recalls by VIN when you have one vehicle's VIN. Use Recalls by YMM when you only know the year, make, and model. Use Recall Campaign when a document carries a manufacturer campaign code. Use Recalls Batch when you need to check thousands of VINs in one job. All four take your API key as the key query parameter.

For complete multi-endpoint sequences, see API Workflows and Real-Life Use Cases.

Who uses this API

Service departments, dealerships, fleet operators, warranty providers, auctions, OEM portals, listing sites, and dealer software vendors call these endpoints before delivery, service, sale, or coverage decisions. They check a single VIN, look up a model line without a VIN, resolve the campaign codes printed on repair orders and owner letters, or scan thousands of VINs in one batch.

Use cases

B2B

• Dealerships — pre-delivery inspection: Flag open recalls and available remedies before a vehicle leaves the lot (Recalls by VIN).
• Service — bay alerts and repair order intake: Look up campaigns, affected components, and fix instructions when a VIN is checked in (Recalls by VIN). Resolve the campaign codes on an incoming repair order before the vehicle reaches the bay (Recall Campaign).
• Fleets — compliance and nightly scans: Submit up to 10,000 VINs and retrieve open-recall status when the batch completes (Recalls Batch). Show open campaigns for a year, make, and model when VINs are not yet assigned or captured (Recalls by YMM).
• Auctions and wholesale: Check a run list of VINs before a sale without issuing one request per vehicle (Recalls Batch). Turn the open-campaign codes on a condition report into readable recall descriptions for buyers (Recall Campaign).
• Dealer groups — lot-wide compliance: Poll or webhook a batch so every store’s inventory is checked on a schedule (Recalls Batch).
• Warranty and claims: Confirm open recalls across assigned vehicles before scheduling work or extending coverage (Recalls by VIN). Confirm a submitted campaign code exists for the make and see whether it is a safety recall or a service bulletin (Recall Campaign).
• Listings — catalog enrichment: Attach known recalls to a YMM listing before a specific VIN is entered (Recalls by YMM).
• OEM and service portals: Power a model-level recall lookup for technicians and support teams (Recalls by YMM).
• Dealer software — service history enrichment: Attach the NHTSA campaign number and description to historical service lines that only carry the manufacturer's code (Recall Campaign).

B2C

• Owner VIN recall checker: Let a vehicle owner paste a VIN and see whether any open safety recalls apply (Recalls by VIN).
• Consumer service apps: Show recall count and remedy status next to a saved vehicle (Recalls by VIN).
• Shop-by-model recall pages: Let a shopper check recalls for a year, make, and model before they have a VIN (Recalls by YMM).
• Vehicle buying research: Show campaign summaries on a comparison or buying-guide page, and let someone considering a used or new vehicle check known model-level recalls before requesting a VIN-specific check (Recalls by YMM).
• Owner letter explainers: Let a vehicle owner type the code from a recall letter and see what the campaign fixes and which models it covers (Recall Campaign).
• Used-vehicle research: Explain the campaign codes shown in a vehicle's service records on a buying-guide or listing page (Recall Campaign).

Recalls Batch has no B2C use cases. A consumer recall checker is a single-VIN lookup; use Recalls by VIN.

Recalls by VIN

Look up all open vehicle safety recalls for a vehicle by VIN. The response tells you how many recalls exist, whether a remedy is available, and the full detail of each campaign — component, risk, and fix instructions.

Parameters

Example

curl -G https://api.carsxe.com/v1/recalls \
  -d key=YOUR_API_KEY \
  -d vin=1C4JJXR64PW696340

Response

Top-level shape

Click data or recalls to expand them and see sample values. For the full interactive reference, try it live in the API Reference.

data

All vehicle-level fields and the recall list are nested under data.

recalls[]

Each item in the recalls array represents one open recall campaign. All fields are optional — a null value means the data source did not provide that information for this campaign.

Recalls by YMM

Retrieve open safety recalls for any vehicle by year, make, and model. No VIN required — ideal for checking an entire model line, powering fleet dashboards, or enriching vehicle listings when individual VINs aren't available.

Parameters

Example

curl -G https://api.carsxe.com/v1/recalls-ymm \
  -d key=YOUR_API_KEY \
  -d year=2026 \
  -d make=toyota \
  -d model=corolla

Response

Top-level shape

Click data or recalls to expand them and see sample values. For the full interactive reference, try it live in the API Reference.

data

All YMM-level fields and the recall list are nested under data.

recalls[]

Each item in the recalls array represents one recall campaign. All fields are optional — a null value means the data source did not provide that information for this campaign.

Recall Campaign

Manufacturers give every recall and service campaign their own code, such as Volkswagen 37M2, and that code is what shows up on repair orders, owner letters, and auction condition reports. The same recall also carries an NHTSA campaign number. This endpoint takes a make and a manufacturer code and returns the campaign behind it: the NHTSA campaign number, whether it is a safety recall or a service bulletin, the defect and remedy description, the affected component, and the models and model years it covers.

Each request is an exact match against the CarsXE campaign dictionary, which covers safety recalls and manufacturer service bulletins. It does not need a VIN.

Parameters

Example

curl -G https://api.carsxe.com/v1/recalls-campaigns \
  -d key=YOUR_API_KEY \
  -d make=volkswagen \
  -d code=37M2

How codes are matched

Matching is exact on the pair of make and code after both are normalized, so these requests all find the same campaign:

• Make is trimmed, repeated spaces are collapsed, and case is ignored. Land Rover and land rover match.
• Code is trimmed, upper-cased, and every letter O is read as the digit 0. 37o2, 37O2, and 3702 match.
• Volkswagen warranty codes match in any spelling. VWP1403, VWP 14 03, and VWP-14-03 all resolve to VWP-14-03.

input.code echoes the code you sent, trimmed. data.campaign_code is the code as the dictionary stores it.

A make and code that are not in the dictionary return 404. The endpoint never guesses a nearby code.

Response

Top-level shape

Click input or data to expand them and see sample values. For the full interactive reference, try it live in the API Reference.

data

Data freshness and coverage

CarsXE refreshes the campaign dictionary regularly and publishes each refresh as a new build. Watch dictionary_version if you cache results on your side.

The dictionary covers campaigns for vehicles sold in the United States. A code a manufacturer used only in another market will not be found.

A campaign covers a range of vehicles inside the listed models and years, not every vehicle built. To confirm whether a specific vehicle is affected and whether the remedy is still open, use the VIN recalls lookup. To see every campaign for a model line, use Recalls by YMM.

Recalls Batch

Submit up to 10,000 VINs in one request for bulk recall checking. Unlike Recalls by VIN, this endpoint is built for high-volume workflows — fleet management, dealership inventory scans, and wholesale auction processing.

How it works

1. Submit — POST VINs (JSON array, inline CSV, or HTTPS URL to a CSV). You receive a batchId immediately (202 Accepted).
2. Poll — Call the status endpoint with batchId until completed, partial, or failed (or wait for your customer webhook).
3. Retrieve — GET results as JSON, or download CSV from /v1/recalls-batch/download.

Caching: Recently checked VINs may be served from cache. If every VIN in the batch is cached, the submit response can already show status: "completed" with full processedVins — no uploading / processing phase.

Full processing path: Uncached VINs move through uploading, then processing, while CarsXE prepares and runs the batch; results are written when processing finishes.

For interactive try-it-live, see the API Reference.

Parameters

Provide at least one of vins, csv, or csvUrl. You can combine them — all VINs are merged and deduplicated. The combined total must not exceed 10,000.

* At least one of vins, csv, or csvUrl is required.

Step 1: Submit a batch

curl -X POST "https://api.carsxe.com/v1/recalls-batch/submit?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vins": [
      "1HGBH41JXMN109186",
      "5YJSA1E26HF000001",
      "1C4JJXR64PW696340"
    ],
    "webhookUrl": "https://your-server.com/webhook"
  }'

Submit with a CSV URL

# Google Sheets sharing link (auto-converted to CSV export)
curl -X POST "https://api.carsxe.com/v1/recalls-batch/submit?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "csvUrl": "https://docs.google.com/spreadsheets/d/YOUR_SHEET_ID/edit"
  }'

Submit response fields

Successful submission returns HTTP 202 with:

Step 2: Check status

Poll until the batch reaches a terminal state. Recommended interval: every 30–60 seconds while uploading or processing.

curl -G "https://api.carsxe.com/v1/recalls-batch/status" \
  -d key=YOUR_API_KEY \
  -d batchId=brb_mnablbn7_wvbaqv

Status response fields

Step 3: Retrieve results

Once status is completed or partial, fetch full recall rows as JSON or download CSV.

curl -G "https://api.carsxe.com/v1/recalls-batch/results" \
  -d key=YOUR_API_KEY \
  -d batchId=brb_mnablbn7_wvbaqv

Results shape

Each VIN has vin, hasRecalls (true if there is at least one safety recall), recallCount, and recalls — an array of sparse camelCase objects:

• Only non-empty string fields and booleans are included per recall.
• Dealer and batch metadata (dealerName, dealerCode, batch name/date fields) are not exposed in JSON.

Common keys when present: recallNhtsaNumber, recallOemNumber, recallTitle, recallDescription, recallRiskDescription, recallRemedyDescription, recallType, recallState, recallStatus, recallIssueDate, severityCode, vehicleYear, vehicleMake, vehicleModel, isRemedied.

CSV download

GET /v1/recalls-batch/download with the same key and batchId. Returns text/csv with a Content-Disposition filename. SDKs also expose a download URL helper (getBulkRecallBatchDownloadUrl / get_bulk_recall_batch_download_url).

curl -G "https://api.carsxe.com/v1/recalls-batch/download" \
  -d key=YOUR_API_KEY \
  -d batchId=brb_mnablbn7_wvbaqv \
  -o recalls_brb_mnablbn7_wvbaqv.csv

Agentic payment access

x402 callers can submit a batch without a CarsXE API key by sending only the JSON vins array. The payment requirement quotes the current bulk_recall_batch starter price multiplied by the number of unique, valid VINs. Inline CSV and csvUrl submissions still require API-key authentication.

After payment, the 202 response includes data.batchToken. Store it securely and send it on every follow-up request; polling, JSON results, and CSV download are included in the original batch payment.

curl -G "https://api.carsxe.com/v1/recalls-batch/results" \
  -d batchId=brb_mnablbn7_wvbaqv \
  -H "X-CarsXE-Batch-Token: <batch-token>"

The token is scoped to one batch, is not included in webhook payloads, and remains valid until the batch job is deleted.

Webhook notifications

If you pass webhookUrl on submit, CarsXE sends an HTTPS POST with Content-Type: application/json when the batch reaches a terminal state (completed or partial). Redirects are not followed. Respond quickly — the request times out on CarsXE’s side after about 30 seconds.

{
  "event": "bulk_recall_batch_complete",
  "batchId": "brb_mnablbn7_wvbaqv",
  "status": "completed",
  "totalVins": 100,
  "processedVins": 100,
  "hitCount": 25,
  "hitRate": 25,
  "downloadUrl": "https://api.carsxe.com/v1/recalls-batch/download?key=…&batchId=…",
  "timestamp": "2026-03-24T10:16:43.000Z"
}

The downloadUrl includes your API key in the query string so you can fetch the CSV without assembling the URL. Your API key is not repeated as a separate JSON field.

Complete example: submit, poll, and retrieve

import { CarsXE } from "carsxe-api";

const carsxe = new CarsXE("YOUR_API_KEY");

const submitResponse = await carsxe.submitBulkRecallBatch({
  vins: [
    "1HGBH41JXMN109186",
    "5YJSA1E26HF000001",
    "1C4JJXR64PW696340",
  ],
});
const batchId = submitResponse.data?.batchId;
if (!batchId) throw new Error("No batchId");
console.log(`Batch submitted: ${batchId}`);

let status;
do {
  await new Promise((r) => setTimeout(r, 30_000));
  status = await carsxe.getBulkRecallBatchStatus(batchId);
  console.log(`Status: ${status.data?.status}`);
} while (
  status.data?.status === "processing" ||
  status.data?.status === "uploading"
);

if (status.data?.status === "completed" || status.data?.status === "partial") {
  const results = await carsxe.getBulkRecallBatchResults(batchId);
  console.log(`Processed: ${results.data?.job.processedVins} VINs`);
  console.log(`Safety recall hits: ${results.data?.job.hitCount}`);

  for (const result of results.data?.results ?? []) {
    if (result.hasRecalls) {
      console.log(`${result.vin}: ${result.recallCount} recall row(s)`);
    }
  }
}

Errors

See the Errors guide for general error handling guidance.

Recalls by VIN:

Recalls by YMM:

Recall Campaign:

Recalls Batch: