Developers / The life of a report

The life of a report

The one page to read before you go to production. What you pay for, what you do not, and why a report sometimes arrives unfinished.

Buying is a POST, reading is a GET

POST /v1/reports buys a report. GET /v1/reports/{reportId} reads one you already bought.

The split is deliberate. If buying were a GET, anything that retries would spend your money without meaning to: an HTTP client default retry policy, a proxy, someone re-running a curl from their shell history. A POST creates the report. Reading it back afterwards can never cost you anything.

Some sections arrive later

A report is assembled from several sources and a few of them are slow. Rather than hold the connection open, we return what we have straight away.

{ "status": "enriching", "pendingSections": ["serviceHistory"] }
  • status: "complete". Everything that is coming has arrived. Nothing further will change.
  • status: "enriching". The report is usable now, but the sections in pendingSections are still being assembled. Read the report back to collect them.

sectionStatus gives the per section detail: ready is present, generating is coming, and none means nothing exists for this vehicle. That last one is not an error and it will not appear later.

Poll every 10 to 15 seconds. Most reports settle within a minute or two. Polling is free, so there is no cost to waiting for complete rather than shipping a half filled report to your users.

What you pay for

You pay per lookup, once, when a report is produced for a vehicle. You do not pay for:

  • Reading a report back. GET /v1/reports/{reportId} is free for 30 days from purchase, however many times you call it. Polling while sections finish is included.
  • Calls that failed. Any response that is not a 200 is never billed: a bad VIN, a rate limit, an outage on our side.
  • Repeat lookups of the same vehicle, within your charge window.

Repeat lookups

If you buy a report for a vehicle you have already bought recently, one of two things happens, depending on what we agreed when your account was set up.

  • Free repeats, the default. A second lookup of the same vehicle within your charge window, normally 24 hours, is free and returns the same reportId. This protects you against your own retries and against two of your workers asking for the same vehicle at once.
  • Every call bills. Some accounts are set up so each completed lookup is charged, even a repeat.

Your setting is on your contract and in your onboarding email, and GET /v1/account shows your charge window. If you are not sure which applies to you, ask before you build around it.

Either way, reading a report back is always free. The setting only affects buying the same vehicle again.

After 30 days

A report stays readable for reportAccessDays, which is 30 unless agreed otherwise, from the moment you bought it. After that, reading it returns 410 REPORT_EXPIRED.

The data has not disappeared. Buy the vehicle again and you get a current report, which is usually what you want by then anyway. If you need a permanent record, store the response your side when you first receive it.

Practical advice

  • Store reportId next to your own record of the vehicle. It is the cheapest way to get the report back.
  • Do not re-buy to refresh. Within the access window, read it back instead.
  • Treat enriching as normal, not as an error. It is the common case for vehicles with a service history.
  • Ignore fields you do not recognise. We add fields to report without changing the version, and a client that rejects unknown fields will break on a routine release.