CheapCarfax API

Get full vehicle history reports by VIN and add them to your own website or app.

Quick start

1. 1. Get your API key from CheapCarfax. It starts with cfc_.
2. 2. Store it on your server (for example as an environment variable CHEAPCARFAX_API_KEY).
3. 3. Request a report with a 17-character VIN:

curl "https://cheapcarfax.co/api/v1/report?vin=1HGCM82633A004352" \
  -H "X-API-Key: YOUR_API_KEY"

Authentication

Send your API key in the X-API-Key header with every request.

X-API-Key: cfc_your_api_key

Get a report

Returns the full vehicle history report for a VIN. You can also send a POST to the same URL with the JSON body {"vin": "..."}.

Generating a new report usually takes 10–60 seconds. Set your HTTP client timeout to at least 120 seconds.

Parameters

Example request

curl "https://cheapcarfax.co/api/v1/report?vin=1HGCM82633A004352" \
  -H "X-API-Key: YOUR_API_KEY"

# or with POST
curl -X POST "https://cheapcarfax.co/api/v1/report" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vin": "1HGCM82633A004352"}'

Example response (200 OK)

{
  "success": true,
  "data": {
    "report_id": "4f2c9a1e-8b7d-4c3a-9e21-0d5f6a7b8c9d",
    "vin": "1HGCM82633A004352",
    "year": 2003,
    "make": "Honda",
    "model": "Accord",
    "generated_at": "2026-10-09T17:43:18.748Z",
    "html_content": "<!DOCTYPE html><html>... full report ...</html>"
  },
  "meta": {
    "cached": false,
    "monthly_limit": 200
  }
}

Response fields

Display & save as PDF

The report is delivered in data.html_content as one complete, styled HTML page. Show it on your website as it is:

<iframe id="report" style="width:100%; height:90vh; border:0;"></iframe>

<script>
  // reportHtml = data.html_content, passed from your server
  document.getElementById("report").srcdoc = reportHtml;
</script>

Saving as PDF

• For your visitors: add a "Download PDF" button that calls iframe.contentWindow.print(). The browser then offers "Save as PDF".
• On your server: convert html_content with any HTML-to-PDF tool (for example Puppeteer, Playwright, wkhtmltopdf or a PDF API).

<button onclick="document.getElementById('report').contentWindow.print()">
  Download PDF
</button>

Usage & monthly limit

Your plan runs in monthly periods that start on the day your plan begins, for example October 14 to November 14. Each period includes a fixed number of reports, and the count starts again from 0 when your plan renews. There is no per-hour or per-minute limit. If a period ends without renewal, requests return 402 until the plan is renewed.

Check your exact period dates and remaining reports at any time. This call is free and never counts:

curl "https://cheapcarfax.co/api/v1/usage" -H "X-API-Key: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "plan": {
      "status": "active",
      "period_start": "2026-10-14T00:00:00.000Z",
      "period_end": "2026-11-14T00:00:00.000Z",
      "days_left": 31
    },
    "usage": { "limit": 200, "used": 3, "remaining": 197 }
  }
}

status is active, ending_soon (5 days or less left) or expired. You can also see the same information in your CheapCarfax dashboard after signing in with your account email.

Errors

Errors return an HTTP status code and a JSON body with error and usually a message. No failed request counts toward your limit.

{
  "error": "Invalid VIN format",
  "message": "VIN must be 17 characters and cannot contain I, O, or Q."
}

Code examples

// Keep the key on your server, e.g. in an environment variable.
const API_KEY = process.env.CHEAPCARFAX_API_KEY;
const BASE_URL = "https://cheapcarfax.co/api/v1";

async function getReport(vin) {
  const res = await fetch(`${BASE_URL}/report?vin=${encodeURIComponent(vin)}`, {
    headers: { "X-API-Key": API_KEY },
  });
  const body = await res.json();
  if (!res.ok) {
    // body.error / body.message explain what went wrong (see "Errors")
    throw new Error(`${res.status}: ${body.message || body.error}`);
  }
  return body.data; // { report_id, vin, year, make, model, html_content, ... }
}
}

Best practices

• Save reports on your side. Store html_content after the first request. Requesting the same VIN again counts as another report.
• Validate the VIN before calling: 17 characters, no I, O or Q.
• Use a timeout of at least 120 seconds. New reports can take up to a minute.
• Retry on 502 / 503 after a short wait. These are never counted.
• Handle 429 by showing your users a friendly message. Do not retry in a loop.
• Never expose your API key in front-end code.

Questions or need a higher limit? Contact support.