API access and report delivery
Use the API from your application's backend. Report acquisition is manually fulfilled; valid reports may be available immediately.
Request access
- Request an API code after signing in with Google. Your verified Google email is used; provide your company and intended use.
- The service owner reviews the request privately and approves or rejects it.
- On approval, the owner selects cache-only or manual-request capability, a cooldown, and a daily limit. Your code is delivered separately by the owner.
Who can see what?
| Visitor | Allowed access |
|---|---|
| Public visitor | This guide and the API-code request form. |
| Approved API customer | Their account settings, their order statuses, and their associated unexpired reports. |
| Service owner | Approval queue, customer management, fulfillment queue, and report store. |
API codes do not grant website administrator access. Customers cannot browse the shared report store or see other customers’ orders. The report store and all management actions are restricted to the designated verified administrator accounts.
Authentication
Keep your code in your server's secret store. Send it as Authorization: Bearer <API_CODE>. Never include it in browser JavaScript, links, analytics, or logs. Requests with browser-origin headers are rejected.
Endpoints
GET /api/v1/carfax/account- Read your capabilities, cooldown, daily limit, and ordering availability.
POST /api/v1/carfax/reports- Send JSON
{"vin":"1HGCM82633A004352"}with a UUIDIdempotency-Key. Save and reuse that key for retries of the same request. New waiting orders return 202; available reports or replays return 200. GET /api/v1/carfax/reports?id=<ORDER_ID>- Read queued, ready, failed, or expired status. Poll queued orders with backoff and follow Retry-After.
GET /api/v1/carfax/report?id=<ORDER_ID>- Download your ready, unexpired PDF with your bearer code. Files are limited to 15 MiB. Other customers' or expired files are unavailable.
Cache and expiration
A matching valid report is reused automatically. Cache-only credentials cannot request a missing report. Reports expire 36 hours after retrieval, not after the latest download. Downloads do not extend validity. No store-listing endpoint is available to customers.
Limits and errors
Each credential has an owner-selected cooldown and daily order limit. The API allows 60 calls per minute per credential. Local daily limits reset at midnight UTC. The shared manual-request cap is separate from the provider's actual account allowance.
Check HTTP status and Content-Type before parsing. 400 means invalid input; 401 invalid or revoked code; 403 forbidden browser request; 404 unavailable report; 409 conflicting retry key; 429 rate or quota limit; 503 new orders paused or the service temporarily unavailable. Database outages return SERVICE_UNAVAILABLE with a 30-second Retry-After. Honor Retry-After. A failed or expired order needs a deliberate new request with a new key; it is never automatically replaced.