CARFAX reports.
One clear integration.

01 · START HERE

Read your account first.

Use a company key supplied separately by AKIS. This read-only call returns the current prices, wallet and ordering status. Every monetary value is an integer number of USD cents.

BASE_URL="https://akis-solutions.com/api/v1/carfax"
# CARFAX_API_KEY is loaded from your server's secret store.
curl "$BASE_URL/account" \
  -H "Authorization: Bearer $CARFAX_API_KEY"

{
  "company": "carreport360.com",
  "currency": "USD",
  "prices": { "STORED": null, "FRESH": null },
  "orderingEnabled": false,
  "wallet": { "balance": 0, "held": 0, "available": 0 },
  "limits": {
    "requestsPerMinute": 60,
    "pendingReports": 5,
    "reportsPerDay": 100
  }
}

1. 1
   Check availability and price

   Read GET /account. Proceed only when ordering is enabled and available credit covers the selected price.

2. 2
   Save one purchase identifier

   Generate a UUID once and persist it with the VIN, mode and quoted price. Use it as the Idempotency-Key for every retry of this purchase.

3. 3
   Order, then poll the returned ID

   Submit POST /reports. Save its response id; poll status initially every five seconds and back off if processing continues.

4. 4
   Deliver the ready document

   When status is ready, download using the bearer endpoint or the five-minute signed link.

02 · AUTHENTICATION

A key for your backend.

Send the header below on account, order, status and direct-download requests. Store the credential in your server’s secret manager and exclude it from client bundles, analytics, URLs and logs.

Authorization: Bearer <CARFAX_API_KEY>

03 · API REFERENCE

Four endpoints. One order.

Append these paths to the base URL. JSON requests and responses use UTF-8. Account and order endpoints accept no query parameters.

{
  "vin": "1HGCM82633A004352",
  "mode": "FRESH",
  "expectedPriceCents": 200
}

# Replace 200 with the current FRESH quote from GET /account.
# Replace the example UUID with your saved purchase UUID.
# Keep the same UUID and body for retries of this purchase.
curl "$BASE_URL/reports" \
  -X POST \
  -H "Authorization: Bearer $CARFAX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 11111111-2222-4333-8444-555555555555" \
  --data '{"vin":"1HGCM82633A004352","mode":"FRESH","expectedPriceCents":200}'

{
  "id": "11111111-2222-4333-8444-555555555555",
  "vin": "1HGCM82633A004352",
  "mode": "FRESH",
  "status": "processing",
  "priceCents": 200,
  "currency": "USD",
  "createdAt": "2026-01-01T12:00:00.000Z",
  "updatedAt": "2026-01-01T12:00:05.000Z",
  "error": null,
  "report": null
}

04 · REPORT LIFECYCLE

Follow the status, not the clock.

Reports are acquired asynchronously. Supplier processing has no promised completion time. Your application’s polling timeout does not cancel an accepted order.

05 · BILLING & RETRIES

One accepted purchase.
One final debit.

• Reuse the same UUID after a lost response or network timeout. Once a key is accepted, changing the VIN, mode or quoted price under that key returns 409 IDEMPOTENCY_CONFLICT.
• Matching pending requests for the same VIN reuse the pending order. Different pending modes or prices return 409 PENDING_REQUEST_CONFLICT.
• An already owned STORED report reopens without another debit. The returned order retains its original purchase mode and priceCents; that field is not a new charge on replay.
• A price change returns 409 PRICE_CHANGED. Read the account again and explicitly approve the new quote before making a new purchase.
• An interrupted submission with no supplier operation fails after five minutes from creation or its first submission start. Retries do not extend that reservation indefinitely.

New orders are currently paused until company pricing and prepaid funding are agreed. Existing order status and completed-document retrieval remain available to authorized accounts. Monthly invoicing is not configured.

06 · LIMITS & ERRORS

Build for predictable retries.

The request-rate limit is shared across the company account, including signed-link downloads. The daily order limit resets at midnight UTC and includes failed orders. Replays and reopens reuse their existing order. JSON request bodies are limited to 8 KiB.

{
  "error": {
    "code": "ORDERING_DISABLED",
    "message": "Report ordering is disabled until company pricing and billing are configured."
  }
}

After a POST timeout or gateway error, an order may already exist. If you have its ID, poll that order. Otherwise, retry the original request with the same saved UUID and unchanged payload after backoff.

A one-minute retry delay does not reset a daily report cap. Wait for the relevant limit to clear or contact AKIS account support.

07 · INTEGRATION FILES

Start with the contract.

import { CarfaxClient } from './carfax-client.mjs';

const client = new CarfaxClient({
  apiKey: process.env.CARFAX_API_KEY,
  baseUrl: 'https://akis-solutions.com/api/v1/carfax'
});

const account = await client.getAccount();
console.log({
  orderingEnabled: account.orderingEnabled,
  prices: account.prices
});

The client exposes getAccount(), requestReport(), getReport(), waitForReport() and downloadReport(). requestReport() takes an explicitly supplied UUID. Polling is bounded and opt-in; purchases are not automatically retried.