Developers / Quickstart

Quickstart

Five minutes from a key to a vehicle report. Every example below is a real request against https://api.mrvin.com. Replace the key with your own.

1. Check your key works

Start here. It costs nothing and it tells you what your account can do.

curl https://api.mrvin.com/v1/account \
  -H "Authorization: Bearer mrvin_live_your_key_here"
{
  "partner": "acme_motors",
  "billingMode": "prepaid",
  "balanceEur": 250.00,
  "creditLimitEur": null,
  "rateLimitPerMinute": 60,
  "reportAccessDays": 30,
  "prices": { "report": 1.50 }
}

prices is what you will be charged per billable call. balanceEur appears for prepaid accounts only. On a postpaid account it is null and creditLimitEur shows your ceiling instead.

If this returns 401, the key is wrong, revoked or expired. All three answer the same way on purpose. Check you copied the whole key, including the mrvin_live_ prefix.

2. Buy a report

curl -X POST https://api.mrvin.com/v1/reports \
  -H "Authorization: Bearer mrvin_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"vin": "WVWZZZ1JZ3W386752"}'
{
  "reportId": "rpt_556e24b94171603dbe7cbdd443513c35",
  "status": "complete",
  "pendingSections": [],
  "vin": "WVWZZZ1JZ3W386752",
  "sectionStatus": { "serviceHistory": "ready", "photos": "ready" },
  "report": { "identity": { "make": "Volkswagen", "model": "Golf", "year": 2003 } }
}

Keep reportId. It is how you read this report again, free, for 30 days.

The response also carries X-Credit-Balance if you are prepaid, so you can watch your balance without a second request.

3. If the report is still being assembled

Some sections take longer than others. When that happens you get the report immediately with status: "enriching" and the outstanding sections listed.

{
  "reportId": "rpt_556e24b9...",
  "status": "enriching",
  "pendingSections": ["serviceHistory"],
  "report": { }
}

Poll the report back every 10 to 15 seconds until status is "complete".

curl https://api.mrvin.com/v1/reports/rpt_556e24b94171603dbe7cbdd443513c35 \
  -H "Authorization: Bearer mrvin_live_your_key_here"
These re-reads are free. You paid for the lookup, not for reading it back. Polling costs you nothing, so there is no reason to hold the first response and hope.

4. Check what you have spent

curl "https://api.mrvin.com/v1/account/usage?from=2026-08-01&to=2026-09-01" \
  -H "Authorization: Bearer mrvin_live_your_key_here"
{
  "from": "2026-08-01", "to": "2026-09-01",
  "totalCalls": 412, "billableCalls": 388, "totalEur": 582.00,
  "days": [{ "day": "2026-08-01", "calls": 14, "billableCalls": 13, "amountEur": 19.50 }]
}

totalCalls and billableCalls differ for good reasons: calls that errored, and repeat lookups of a vehicle you already bought.

What to build next

  • Handle 402. It means top up, not retry.
  • Respect X-RateLimit-Remaining rather than discovering the limit by hitting it.
  • Read the life of a report before going to production. It is short, and it is the difference between paying once per vehicle and paying every time.