Skip to main content

Retrieving a Glass's Historical Valuation via the MotorSpecs API

Use case: Retrospectively determine the market value of a vehicle at a specific date in the past — for example, to assess what a car was worth at the time of an accident.

Written by Shane
Updated today

Before You Begin

Confirm your API account has the following endpoints active and that you are working against the staging environment before going live:

  • Identity

  • Historical VIN

  • Valuation Glass's Fetch Natcode

  • Glass's Valuation (by NAT code)

If any of these aren't active just reach out to customer support and we'll enable them for you.

Overview: Two Flows

The process differs depending on whether the registration number (VRM) provided by the enquirer is still associated with the same vehicle.

Flow A — The VRM is still on the same car (most common)

Flow B — The VRM is a private plate that has since moved to a different vehicle

In both cases, the end goal is the same: obtain the correct NAT code for the vehicle as it was at the time of the accident, then use that to retrieve the historical valuation.

What to Collect Upfront

Before making any API calls, ask the enquirer for:

  • The VRM of the vehicle

  • The date of the incident

  • The mileage at the time

You can collect all three on a single screen at the start of the flow.

Flow A — VRM Is Still on the Same Vehicle

Step 1 — Identity Lookup

Call the Identity service to retrieve the vehicle's details:

POST https://staging.motorspecs.com/identity/lookup

Return the Make, Model, Colour, and first registration date to the user and ask them to confirm this is the correct vehicle. If they say no, the VRM may have changed — move to Flow B.
​

Step 2 — Fetch the NAT Code

Call the Glass's Fetch Natcode endpoint, passing the confirmed VRM:

POST https://staging.motorspecs.com/valuation-glass/natcode-by-vrm

Extract and store the <QualifiedModelCode> value from the response. You will need this for the valuation call — store it against the vehicle record at this point.
​

Step 3 — Retrieve the Historical Valuation

Call the Glass's valuation endpoint with the NAT code:

POST https://staging.motorspecs.com/valuation-glass/by-nat-code/value

Required payload fields:

Field

Source

country

Always "UK"

natCode

QualifiedModelCode from Step 2

firstRegistrationDate

regDate from the identity response in Step 1

valuationDate

Date of the accident (collected upfront)

currentMiles

Mileage at time of accident (collected upfront)

commercial

0 for non-commercial vehicles

Flow B — VRM Has Since Moved to Another Vehicle

If the identity lookup returns a vehicle the enquirer doesn't recognise, the VRM is likely a private plate that has transferred to a different car. Use the following steps to trace back to the correct vehicle.
​

Step 1a — Historical VIN Lookup

Call the historical VIN endpoint, passing the VRM and the date of the accident:

POST https://staging.motorspecs.com/historical-vin/check

This returns the VIN that was associated with that plate on the date in question.

Example payload:

json

{   "vrm": "J12RPH",   "date": "2021-10-15" }


Step 1b — Identity Lookup by VIN

Using the VIN returned above, repeat the identity lookup — this time with the VIN as the identifier rather than the VRM:

json

{   "vin": "WBA1S920405H12465",   "currentMiles": 100000 }

This gives you the vehicle details and, importantly, the current registration number associated with that VIN. Confirm with the enquirer that this is the correct vehicle.

Why this matters: The Glass's Fetch Natcode endpoint works off the current VRM. If you pass a historical or transferred plate, you'll get the NAT code for the wrong car and the valuation will be incorrect.


Steps 2 and 3 — As per Flow A

Once you have the correct current VRM from Step 1b, proceed with the NAT code fetch and historical valuation call exactly as described in Flow A above.

Interpreting the Response

A successful valuation response will include an adjustedConsumerValues block. The key figure is:

"adjustedConsumerValues": {   "retailTransacted": 2845 }

retailTransacted is the figure you should use for historical valuations. It represents the actual transacted market price at the date in question, not simply the listed retail value.

Note on date ranges: For valuations dated prior to December 2025, retailTransacted will differ from retailValue and is the more accurate historical market figure. From December 2025 onwards, the two values are aligned.

We recommend storing all returned valuation fields against the record — not just retailTransacted — for audit and reference purposes.

Support

If you encounter issues during integration, contact the technical support team at techsupport@motorspecs.co.uk. Include your API account name in any query to help the team assist you as quickly as possible.

Did this answer your question?