Making a lookup: request and response

A single lookup is one authenticated request to a product's live endpoint.

The request

curl "https://vehiclematic.com/products/vehicle-details/api/live/AB12CDE" \
  -H "X-VEHICLEMATIC-KEY: your_api_key"

The last path segment is the registration (VRM). Both GET and POST are accepted.

The response

You get back normalized JSON: a data object with the product's fields, and your remaining credit_balance (in pence). A _meta block inside data reports whether the result was served from cache.

{
  "data": {
    "registration": "AB12CDE",
    "make": "FORD",
    "colour": "BLUE",
    "fuel_type": "PETROL",
    "tax_status": "Taxed",
    "mot_status": "Valid",
    "_meta": { "cache": "hit" }
  },
  "credit_balance": 4850
}

The _meta.cache value is hit, miss, hot or mixed (the last for multi-source products). You're only charged for fresh data, so a cached result within the caching window doesn't cost another credit.

CSV output

Add ?format=csv to get the same rows flattened to CSV instead of JSON — handy for spreadsheets and bulk exports.

Errors

• Missing registration → 422 with a message.
• Insufficient credits → 402, including your current credit_balance so you can prompt a top-up.
• Invalid or missing key → an authentication error (see Authenticating your API requests).

Next

• Bulk lookups
• Rate limits and reliable requests