v1.0.2

API Documentation

Welcome to RecallAPI.

Get familiar with the endpoints and their data.

Or click here to view information on batch processing.

 Recall Report API


The Recall Report API provides access to a library of vehicle and recall data.

HTTPS calls are made to RecallAPI using the GET method with the endpoint listed in this section. Please see below for the complete documentation and access details.

GET https://www.recallapi.com/api/v1/vehicle/

 Authentication


Before being able to use this API, you must register. Authentication is done via the API key which you can find in your account settings.

You can see your account’s API keys, and refresh them if necessary, in the user dashboard.

 Quick Start


Once you are registered and have your API key, you are ready to begin checking for recalls!

The API is organized around REST. All request and response bodies, including errors, are encoded in JSON.

You will not need any specific language bindings to use this API. But for your convenience, we've provided quick start code snippets to get you on your way.

You can switch the programming language of the examples with the tabs at the top.


# nethttp2.rb
require 'uri'
require 'net/http'

uri = URI('https://www.recallapi.com/api/v1/vehicle/recallReport')
params = { :token => YOUR_API_KEY, :vin => VIN }
uri.query = URI.encode_www_form(params)

res = Net::HTTP.get_response(uri)
puts res.body if res.is_a?(Net::HTTPSuccess)


import requests

url = "https://www.recallapi.com/api/v1/vehicle/recallReport"

params = {
    "token":YOUR_API_KEY,
    "vin":VIN
}

response = requests.request("GET", url, params=params)

print(response.text)


$ch = curl_init();

$url = "https://www.recallapi.com/api/v1/vehicle/recallReport";

$dataArray = [
    'token' => YOUR_API_KEY,
    'vin' => VIN
];

$data = http_build_query($dataArray);

$getUrl = $url."?".$data;

curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $getUrl);
    
$response = curl_exec($ch);
curl_close($ch);


const http = require('http');
const querystring = require('querystring');

const parameters = {
	token: YOUR_API_KEY,
	vin: VIN
}

const get_request_args = querystring.stringify(parameters);

const options = {
	url: "https://www.recallapi.com/api/v1/vehicle/recallReport",
	path: "?" + get_request_args,
	headers : {
		'Content-Type': 'application/x-www-form-urlencoded'
	}
}

const request = http.request(options, (response) => {
	let all_chunks = [];

	response.on('data', (chunk) => {
		all_chunks.push(chunk);
	});

	response.on('end', () => {
		let response_body = Buffer.concat(all_chunks);
		console.log(response_body.toString());
	});

	response.on('error', (error) => {
		console.log(error.message);
	});
});

request.on('error', (error) => {
	console.log(error.message);
});

request.end();


curl --request GET
  --url 'https://www.recallapi.com/api/v1/vehicle/recallReport'
  --header 'accept: application/json'
  --header 'content-type: application/json'
  --data '{"token": YOUR_API_KEY}'
  --data '{"vin": VIN}'

 Errors


Our API uses conventional HTTP response codes to indicate the success or failure of an API request.

In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with our servers (these are rare).

Some 4xx errors that could be handled programmatically (e.g., invalid VIN, modelYear outside of datarange, etc.) include an error code that briefly explains the error reported.

HTTP Status Code Summary
200 Okay Everything worked as expected.
400 Bad Request The request was unacceptable, often due to missing a required parameter.
401 Unauthorized No valid API key provided.
402 Request Failed The parameters were valid but the request failed.
403 Forbidden The API key doesn't have permissions to perform the request.
404 Not Found The requested resource doesn't exist.
422 Validation Error A validation error occurred.
429 Too Many Requests Too many requests hit the API too quickly.
500, 502, 503, 504 Internal Server Error Something went wrong on our end.

 Recall Report Attributes


Recall Reports are returned in JSON format, containing the following list of data fields, as applicable.

uuidstring

A 128-bit label used to uniquely identify the recall report and its data.

vinstring

Alphanumeric 17-digit vehicle identification number (VIN).

manufacturerstring

Name of the vehicle manufacturer.

modelYearint

Model year of the vehicle conveyed as a four-digit integer in format YYYY.

makestring

Per 49 CFR 565, Make is a name that a manufacturer applies to a group of vehicles or engines.

modelstring

Per 49 CFR 565, Model means a name that a manufacturer applies to a family of vehicles of the same type, make, line, series and body type.

vehicleTypestring

Defines the type of the vehicle based on the World Manufacturer Identifier (WMI). Common types include Passenger Car, Multipurpose Passenger Vehicle (MPV), Truck, and Motorcycle.

reportDatedatetime

The date and time the report was generated conveyed in ISO 8601 format YYYY-MM-DDTHH:mm:ssZ.

hasRecallsboolean

Indicates if a vehicle has open recalls at the time the report is generation. A vehicle with open recalls will return true, a vehicle without open recalls will return false.

recallCountint

An integer representation of the number of open recalls for the queried vehicle.

recallsarray

Returns an array with campaign-specific details on open recalls. If there are no open recalls associated with the vehicle, an empty array will be returned.

{
    "uuid": "8a1caec6-e120-4360-abd1-b888298a9ea4",

    "vin": "1FM5K8HT1HGD03221",

    "manufacturer": "FORD MOTOR COMPANY, USA",

    "modelYear": "2017",

    "make": "FORD",

    "model": "Explorer",

    "vehicleType": "MULTIPURPOSE PASSENGER VEHICLE (MPV)",

    "reportDate": "2021-11-29 13:32:56",

    "hasRecalls": TRUE,

    "recallCount": 1,
    
    "recalls": []
}

 Recall Campaign Attributes


If a vehicle has open recalls, the details of the specific recall campaign will be appended to the recalls array in the Recall Report.

Any missing values should be interpreted as RecallAPI does not have data on the specific attribute or variable. Missing values should NOT be interpreted as an indication that an attribute or variable does not apply.

recallDatedate

The date the recall was issued conveyed in ISO 8601 format YYYY-MM-DD.

expirationDatedate

If applicable, the date of expiration for the issued recall conveyed in ISO 8601 format YYYY-MM-DD. If not applicable, this field will be blank.

nhtsaIdstring

Six character alphanumeric code indicating the NHTSA campaign ID. If campaign type is not NHTSA, this field will be blank.

manufacturerIdstring

Identifier the manufacturer assigns to the campaign. The ID format depends on the manufacturer.

recallCampaignTypestring

Campaign type will be listed as either NHTSA or VOLUNTARY/SERVICE.

recallNamestring

Common name of the recall campaign.

componentstring

Specific component(s) affected by the recall.

recallDescriptionstring

Description of the conditions of the recall campaign.

riskDescriptionstring

Description of the risks and potential safety consequences of the defect.

stopSaleboolean

Indicates if a stop-sale order is in place at the time the report is generated.

dontDriveboolean

Indicates if don't drive directive is in place at the time the report is generated.

remedyAvailableboolean

Indicates if a remedy has been issued for the stated recall at the time the report is generated.

recallRemedystring

Description of the approved recall remedy or corrective action.

partsAvailableboolean

Indicates if parts are available for the stated remedy at the time the report is generated.

laborHoursMinfloat

Indicates minimum number of labor hours for service.

laborHoursMaxfloat

Indicates maximum number of labor hours for service.

recallStatusstring

Indicates the status of the recall on the 17-digit specific VIN at the time the report is generated. Values will be listed as Incomplete or Complete.

{
    "recallDate": "2021-09-24",

    "expirationDate": "",

    "nhtsaId": "21V537",

    "manufacturerId": "21S32",

    "recallCampaignType": "NHTSA",

    "recallName": "REAR TOE LINK REPLACEMENT",

    "component": "SUSPENSION:REAR",

    "recallDescription": "VEHICLES EXPOSED TO A CORROSIVE ENVIRONMENT WHERE ROAD SALT IS USED EXTENSIVELY DURING WINTER MONTHS COULD EXPERIENCE A SEIZED REAR SUSPENSION TOE LINK BALL JOINT RESULTING IN A FRACTURED REAR SUSPENSION TOE LINK.",

    "riskDescription": "A REAR TOE LINK FRACTURE MAY CAUSE A LOSS OF STEERING CONTROL, INCREASING THE RISK OF A CRASH.",

    "stopSale" : TRUE,

    "dontDrive" : FALSE,

    "remedyAvailable": TRUE,

    "recallRemedy": "AN INTERIM INSPECTION WAS PREVIOUSLY COMPLETED ON YOUR VEHICLE RECALL 20S62. HOWEVER, ITS REQUIRED THAT YOU BRING YOUR VEHICLE IN FOR A SECOND INSPECTION TO ENSURE CONTINUED SAFE OPERATION OF YOUR VEHICLE UNTIL THE FINAL REPAIR CAN BE COMPLETED. WHEN PARTS ARE AVAILABLE FOR THE FINAL REPAIR, FORD MOTOR COMPANY WILL NOTIFY YOU VIA MAIL TO SCHEDULE A SERVICE APPOINTMENT WITH YOUR DEALER FOR REPAIRS TO BE COMPLETED FREE OF CHARGE PARTS AND LABOR. DEALERS WILL INSPECT AND REPLACE AS NECESSARY THE REAR SUSPENSION TOE LINK BALL JOINTS AND KNUCKLES, WILL INSTALL UPGRADED REAR SUSPENSION TOE LINKS, AND ADJUST REAR WHEEL ALIGNMENT FREE OF CHARGE. FORD MOTOR COMPANY IS WORKING CLOSELY WITH ITS SUPPLIERS TO PRODUCE PARTS FOR THIS REPAIR.",

    "partsAvailable": FALSE,

    "laborHoursMin" : 0.6,

    "laborHoursMax" : 1.2,

    "recallStatus": "Incomplete"
}

 Batch Processing


Need to operate at scale? RecallAPI offers batch recall report processing to enterprise accounts, allowing for bulk VIN checks via SFTP handoffs.

Simply upload a list of VINs in a .csv file to your organization's authorized account, and RecallAPI will process the records and place the outfile directly in your secure file for retrieval.

Batch data output contains the same recall report attributes and recall campaign attributes as the single-call API, but returns the information in a consolidated .csv outfile.

Need to track your VIN records for accounting or client identification? RecallAPI's batch processing allows you to include unique IDs for the batch and/or the VINs it contains, which are preserved throughout data processing.