Recall Campaign Number API

You need to programmatically identify and track official U.S. safety recalls for vehicles and reference them reliably in your apps. By the end of this guide, you’ll know how to query the Vehicle API Recall endpoint, extract the recall campaign number for a VIN, store and cache it, and build robust error handling around coverage limits and nulls—all with a single request you can ship today.

What a Recall Campaign Number Is and Why You Should Store It

The recall campaign number is the authoritative identifier NHTSA assigns to each recall (for example, 19V182000). You will use this field to:

• De-duplicate and track recall records across your systems.
• Link UI components (e.g., “View recall details”) and workflows (e.g., outreach tasks) to a single primary key.
• Cache recall results per vehicle or per make–model–year slice.

In Vehicle API, this value lives at data.recalls[].campaign in the Recall endpoint response. Coverage for recalls is U.S.-market only, matched by make + model + year. This endpoint does not indicate whether a specific vehicle has already been repaired.

Endpoint Overview

Base URL: https://vehicles-api.com/api/v1

Endpoint: GET /vin/recalls

Auth: X-API-Key: YOUR_API_KEY (Authorization: Bearer YOUR_API_KEY also works)

Parameters:

• vin (query): The vehicle identification number you want to check.

Response envelope:

• status: "success" or "error"
• source: "nhtsa" on success for recalls
• data: payload when status is success
• error: object with code and message when status is error

Coverage and matching model:

• Recalls are U.S.-market only. A valid non-U.S. VIN for this endpoint returns an error with code coverage_us_only.
• Matches are by make + model + year, not per serial number. This is not a vehicle history report and does not include title, accident, or ownership history.

Other product scope notes you may need during integration:

• VIN decoding works worldwide but is fullest for U.S.-market vehicles.
• Dutch plates come from RDW open data and never include a VIN.
• There is no live U.S. plate lookup in this API.

Quickstart: cURL You Can Paste

Use the control VIN below (a 2003 Honda Accord) to validate your integration. This is a docs example, not your target vehicle.

curl "https://vehicles-api.com/api/v1/vin/recalls?vin=1HGCM82633A004352" -H "X-API-Key: YOUR_API_KEY"

Official JSON Response

The following is the official example from the documentation. Live recall counts and campaigns evolve as NHTSA publishes updates; your production queries may return additional or different campaigns for the same make–model–year over time.

{
"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 use in production:

• data.recalls[].campaign: The recall campaign number you will store and use as a stable primary key for each recall.
• data.count: Total number of recalls matched for the make–model–year. Useful for summary metrics and pagination in your UI (client-side).
• data.recalls[].component, summary, consequence, remedy: Text details to display in user interfaces or messaging.
• data.recalls[].received: Date string in YYYY-MM-DD; represents when NHTSA received the recall. Use for sorting and change detection.
• data.vin, data.year, data.make, data.model: Useful context for logs and cache keys.
• status, source: Envelope metadata; source is "nhtsa" for this endpoint.

JavaScript Example: Fetch and Store Recall Campaign Numbers

This JavaScript snippet calls the same endpoint, handles envelope semantics, and extracts the campaign numbers. Replace YOUR_API_KEY with your key before running.

async function getRecallCampaignNumbers(vin) {
const url = `https://vehicles-api.com/api/v1/vin/recalls?vin=${encodeURIComponent(vin)}`;
const res = await fetch(url, {
headers: {
'X-API-Key': 'YOUR_API_KEY'
}
});

// Handle non-2xx HTTP in a generic way; body will still use the envelope.
const body = await res.json();

if (body.status !== 'success') {
const code = body.error && body.error.code ? body.error.code : 'unknown_error';
const msg = body.error && body.error.message ? body.error.message : 'Request failed';
throw new Error(`Vehicle API error: ${code} - ${msg}`);
}

const recalls = Array.isArray(body.data.recalls) ? body.data.recalls : [];
// Extract campaign numbers (the primary key to store)
const campaigns = recalls
.map(r => r && r.campaign)
.filter(Boolean);

return {
vin: body.data.vin,
make: body.data.make,
model: body.data.model,
year: body.data.year,
coverage: body.data.coverage,
count: body.data.count,
campaigns,
// Keep the raw recalls array if you want to render details
recalls
};
}

// Example usage with the docs control VIN (not your vehicle)
getRecallCampaignNumbers('1HGCM82633A004352')
.then(result => {
console.log('Campaign numbers:', result.campaigns);
// Cache per VIN or per make-model-year as needed
})
.catch(err => {
console.error(err.message);
});

How Matching and Coverage Affect Your Results

Recall coverage is U.S.-market only for this endpoint. If you query a valid non-U.S. VIN here, you will receive an error with code coverage_us_only in the envelope. Successful matches are by make + model + year, so your results represent all recall campaigns that apply to that configuration, not the unit-specific repair status.

When building dealer tools, marketplaces, fleet dashboards, insurance apps, or AI agents, design your UX and logic with these constraints:

• Do not interpret an empty recalls array as “no safety risk.” It may indicate lack of U.S. coverage for the queried VIN or a model with zero campaigns.
• Always present recall status as “campaigns that apply to this make–model–year,” not “this VIN was repaired.” If you need repair completion, consult OEM service records separately.
• If you serve multiple markets, gate this endpoint behind a market flag. Offer alternative content when coverage_us_only is returned.

Field Behavior, Nullability, and Data Types

Be ready for nulls in descriptive fields. The envelope and structural keys are stable, but descriptive strings (component, summary, consequence, remedy) can be empty or null for some records. Recommended handling:

• recalls[].campaign: Required identifier; treat as the stable key to de-duplicate.
• recalls[].received: Parse as a date string in UTC (YYYY-MM-DD). If absent, default-sort by campaign or push to the end.
• recalls[].component, summary, consequence, remedy: Display if present; otherwise, suppress the field label in UI.
• count: Integer; prefer server-provided count over client-side length if you later add server-side filters.

Caching Strategy for Recall Campaign Numbers

Campaign numbers are stable identifiers but the list can grow as new campaigns are published. Suggested caching approach:

• Cache per VIN key: recalls:{vin} with the array of campaign numbers and a short TTL (e.g., daily) so new campaigns propagate quickly.
• Also maintain a per make–model–year cache if you routinely query many VINs from the same configuration. This can reduce duplicate lookups.
• On cache refresh, compute set difference to detect newly added campaign IDs for notifications.
• Never assume recall lists are immutable; schedule periodic refreshes for active fleets and inventory.

Error Handling and Quotas

Every response uses the envelope described above. On error, status is "error" and the body includes error.code and error.message. Common scenarios include:

• coverage_us_only: The VIN is valid but recall coverage is U.S.-only for this endpoint.
• Authentication issues: Ensure the X-API-Key header (or Authorization: Bearer) is present and valid.
• Input validation: Ensure you pass a VIN via vin= in the query string.

Rate limits and monthly quotas depend on your plan. If you encounter throttling, use exponential backoff and respect Retry-After headers if present. Batch your reads where possible, cache aggressively as outlined above, and monitor your usage. For plan specifics and current limits, see the Documentation.

Designing Your Data Model Around recalls[].campaign

Use the campaign number as the canonical primary key for each recall in your database:

• Primary table: recall_campaigns keyed by campaign, with component, summary, consequence, remedy, received.
• Association: vehicle_recalls linking vehicles (by VIN or internal vehicle_id) to campaign numbers.
• De-duplication: Upsert by campaign to avoid duplicates when refreshing from the API.
• Change detection: Compare stored campaigns to current API response to detect new or removed campaigns.

This structure supports inventory-wide rollups (e.g., “vehicles impacted by 19V182000”) and targeted outreach.

UI and Agent Patterns That Use the Campaign Number

• Inventory cards: Show count and the newest campaign’s received date; link to a detail drawer keyed by campaign.
• Fleet operations: Sort campaigns by received to prioritize recent safety items.
• Insurance underwriting: Flag specific campaign IDs in risk rules without parsing free text.
• AI agents: Use campaign as the reference token. When generating messages, cite the campaign ID and component to remain anchored to authoritative data.

Practical Integration Notes

• Time zones: received is a date string; treat as UTC and render in the user’s locale if needed.
• International VINs: For recall lookups, return coverage_us_only on valid non-U.S. VINs. For VIN decoding needs outside the U.S., use the decode endpoint (worldwide, fullest for U.S.), then conditionally run recalls.
• Dutch plates: Plate-based lookups from RDW never return a VIN. If you need recalls, require a VIN from your user or upstream system.
• This is not a vehicle history report: No title, accident, or ownership information is included or implied. Recalls are matched by make–model–year.
• MCP server: If you are building agents or tools that prefer an MCP integration, Vehicle API is also available via MCP at MCP.

Testing and Observability

• Use the control VIN 1HGCM82633A004352 for repeatable tests as you build. Do not treat it as your customer’s vehicle.
• Log the envelope fields status and source alongside vin, year, make, model to aid debugging and cache verification.
• Surface error.code to client logs, especially coverage_us_only, to distinguish coverage from validation/auth issues.
• Implement structured metrics: recall_lookup.success, recall_lookup.error.by_code, and recall_cache.hit/miss.

Security and Key Management

• Send keys via HTTPS with the X-API-Key header as shown in examples. Authorization: Bearer also works if your client standardizes on that format.
• Do not embed keys in mobile or browser code without a proxy. Use a backend service to sign requests or forward responses.
• Rotate keys regularly and monitor usage in your API account dashboard.

Operational Playbook: Handling Growth in Live Data

Recall data changes as NHTSA publishes updates and manufacturers add campaigns. To keep your campaign set fresh and auditable:

• Refresh cadence: Re-query active inventory at a schedule that fits your SLA (e.g., daily). Honor cache TTLs you set.
• New campaign detection: Alert when a previously unseen data.recalls[].campaign appears for a tracked VIN or configuration.
• Backfill: When you add a new make–model–year, run an initial sweep and cache campaign sets to avoid cold starts for users.
• User notifications: Use the campaign number in user-facing messages so recipients can verify the recall independently.

Putting It All Together

To ship a production-grade Recall Campaign Number integration:

1. Call GET /vin/recalls with your user’s VIN and X-API-Key.
2. Check the response envelope. On success, iterate data.recalls[].campaign and persist the IDs.
3. Cache results per VIN with a short TTL and compare sets to detect newly added campaign numbers.
4. Handle coverage_us_only errors and present alternate UX for non-U.S. vehicles.
5. Render component, summary, consequence, and remedy conditionally; suppress labels if fields are null.
6. Monitor rate limits and quota; apply backoff and batching as needed. See the Documentation for plan details.

FAQs

Does the Recall endpoint tell me if a specific VIN was already repaired?
No. Results are matched by make + model + year and do not indicate repair completion for the specific vehicle. Use OEM or service records for repair status.

What happens if I query a non-U.S. VIN?
For this endpoint, recall coverage is U.S.-market only. You will receive an error with error.code coverage_us_only in the envelope for valid non-U.S. VINs.

Is the recall campaign number unique?
Yes. data.recalls[].campaign is the authoritative identifier for a recall campaign; use it as your primary key for de-duplication and linking.

How often should I refresh recall data?
Because new campaigns can be added, refresh on a schedule appropriate for your business (e.g., daily for active fleets or inventories). Cache results and compute set differences to detect new campaigns.

Can I get recalls from a Dutch plate?
No. Dutch plates (from RDW open data) do not include a VIN, and this Recall endpoint requires a VIN. If you have both, run the recall lookup using the VIN.

Start integrating the Recall Campaign Number API now and ship a reliable safety experience. Every plan includes a 7-day free trial, and the Starter plan begins at $19/month. Create your account and get your API key here: Register. For agent integrations, see the MCP server at MCP, and keep the full API reference handy in the Documentation.